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Chapter 1: Getting started with common-lisp 


Remarks 


This is a simple hello world function in Common Lisp. Examples will print the text He110, world! 
(without quotation marks; followed by a newline) to the standard output. 


Common Lisp is a programming language that is largely used interactively using an interface 
known as a REPL. The REPL (Read Eval Print Loop) allows one to type code, have it evaluated 
(run) and see the results immediately. The prompt for the REPL (at which point one types the code 
to be run) is indicated by c1-user>. Sometimes something other than c1-user will appear before the 
> but this is still a REPL. 








After the prompt comes some code, usually either a single word (i.e. a variable name) or a form (a 
list of words/forms enclosed between ( and )) (i.e. a function call or declaration, etc). On the next 
line will be any output that the program prints (or nothing if the program prints nothing) and then 
the values returned by evaluating the expression. Normally an expression returns one value but if 
it returns multiple values they appear once per line. 


Versions 
Common Lisp 1984-01-01 


ANSI Common Lisp 1994-01-01 


Examples 


Hello World 


What follows is an excerpt from a REPL session with Common Lisp in which a "Hello, World!" 
function is defined and executed. See the remarks at the bottom of this page for a more thorough 
description of a REPL. 


CL-USER> (defun hello () 
(format t "Hello, World!~%")) 








H 

CL-USER> (hello) 
Hello, World! 
N 
E 




















i-USER> 





This defines the "function" of zero arguments named he110, which will write the string "Heilo, 
world!" followed by a newline to standard output, and return nit. 
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To define a function we write 


(defun name (parameters...) 
code...) 


In this case the function is called ne110, takes no parameters and the code it runs is to do one 
function call. The returned value from a lisp function is the last bit of code in the function to run so 
hello returns whatever (format t "Hello, World!~%") returns. 


In lisp to call a function one writes (function-name arguments...) Where function-name is the name of 
the function and arguments... is the (Space-separated) list of arguments to the call. There are 
some special cases which look like function calls but are not, for example, in the above code there 
iS NO defun function that gets called, it gets treated specially and defines a function instead. 


At the second prompt of the REPL, after we have defined the re110 function, we call it with no 
parameters by writing (he110). This in turn will call the format function with the parameters + and 
"Hello, World!~%". The format function produces formatted output based on the arguments which it 
is given (a bit like an advanced version of prints in C). The first argument tells it where to output 
to, with t meaning standard-output. The second argument tells it what to print (and how to interpret 
any extra parameters). The directive (special code in the second argument) ~s tells format to print 
a newline (i.e. on UNIX it might write \n and on windows \r\n). Format usually returns wrt (a bit like 
nuLL in other languages). 


After the second prompt we see that Hello, wor1a has been printed and on the next line that the 
returned value was nit. 


Hello, Name 
This is a slightly more advanced example that shows a few more features of common lisp. We 
start with a simple e110, woria! function and demonstrate some interactive development at the 


REPL. Note that any text from a semicolon, ;, to the rest of the line is a comment. 


CL-USER> (defun hello () 
(format t "Hello, World!~%")) ;We start as before 








CL-USER> (hello) 
Hello, World! 











CL-USER> (defun hello-name (name) ;A function to say hello to anyone 

(format t "Hello, ~a~%" name)) ;~a prints the next argument to format 
HE LLO-NAME 
CL-USER> (hello-name "Jack") 
Hello, Jack 



























































NIL 
CL-USER> (hello-name "jack") ¡doesn't capitalise names 
Hello, jack 
elk 
CL-USER> (defun hello-name (name) ;format has a feature to convert to title case 
(format t "Hello, ~:(~a~)~%" name)) ;anything between ~:( and ~) gets it 
WARNING: redefining COMMON-LISP-USER: :HELLO-NAME in DEFUN 
HELLO-NAME 























CL-USER> (hello-name "jack") 
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Hello, Jack 






























































NIL 
CL-USER> (defun hello-name (name) 
(format t "Hello, ~:(~a~)!~%" name) ) 
WARNING: redefining COMMON-LISP-USER::HELLO-NAME in DEFUN 
HELLO-NAME 
CL-USER> (hello-name "jack") ¿now this works 
Hello, Jack! 
NIL 
CL-USER> (defun hello (&optional (name "world")) ;we can take an optional argument 
(hello-name name)) ¿name defaults to "world" 
WARNING: redefining COMMON-LISP-USER::HELLO in DEFUN 
HELLO 








CL-USER> (hello) 
Hello, World! 


N 
CL-USER> (hello "jack") 
Hello, Jack! 





































































































































































































NIL 
CL-USER> (hello "john doe") ¿note that this capitalises both names 
ello, John Doe! 
NIL 
CL-USER> (defun hello-person (name &key (number) ) 
(format t "Hello, ~a ~r" name number)) ;~r prints a number in English 
HE LLO-PERSON 
CL-USER> (hello-person "Louis" :number 16) ;this doesn't quite work 
Hello, Louis sixteen 
NIL 
CL-USER> (defun hello-person (name &key (number) ) 
(format t "Hello, ~:(~a ~:r~)!" name number)) ;~:r prints an ordinal 
WARNING: redefining COMMON-LISP-USER::HELLO-PERSON in DEFUN 
HELLO-PERSON 
CL-USER> (hello-person "Louis" :number 16) 
Hello, Louis Sixteenth! 
NIL 
CL-USER> (defun hello-person (name &key (number) ) 
(format t "Hello, ~:(~a ~@r~)!" name number)) ;~@r prints Roman numerals 
WARNING: redefining COMMON-LISP-USER::HELLO-PERSON in DEFUN 
HELLO-PERSON 
CL-USER> (hello-person "Louis" :number 16) 
Hello, Louis Xvi! 
NIL 
CL-USER> (defun hello-person (name &key (number)) ;capitalisation was wrong 
(format t "Hello, ~:(~a~) ~:@r!" name number) ) 
WARNING: redefining COMMON-LISP-USER::HELLO-PERSON in DEFUN 
HELLO-PERSON 
CL-USER> (hello-person "Louis" :number 16) ¡thats better 
Hello, Louis XVI! 
NIL 
CL-USER> (hello-person "Louis") ¡we get an error because NIL is not a number 
Hello, Louis ; Evaluation aborted on #<SB-FORMAT:FORMAT-ERROR (1006641AB3)>. 
CL-USER> (defun say-person (name &key (number 1 number-p) 
(title nil) (roman-number t)) 
(let ((number (if number-p 
(typecase number 
(integer 
(format nil (if roman-number " ~:@r" " ~: (~:r~)") number) ) 
(otherwise 
(format nil " ~:; (~a~)" number) )) 





"")) ; here we define a variable called number 
(erele (Gli title 
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(oran ac le) 
UN) $ eme here one Called tell 









































































































































(format nil "~a~: (~a~)~a" title name number))) ¡we use them her 
SAY PERSON 
CL-USER> (say-person "John") ;some examples 
"John" 
CL-USER> (say-person "john doe") 
"John Doe" 
CL-USER> (say-person "john doe" :number "JR") 
"John Doe Jr" 
CL-USER> (say-person "john doe" :number "Junior") 
"John Doe Junior" 
CL-USER> (say-person "john doe" :number 1) 
"John Doe I" 
CL-USER> (say-person "john doe" :number 1 :roman-number nil) ¡this is wrong 
"John Doe First" 
CL-USER> (defun say-person (name &key (number 1 number-p) 
(title nil) (roman-number t)) 
(let ((number (if number-p 
(typecase number 
(integer 
(format nil (if roman-number " ~:@r" " the ~: (~:r~)") number) ) 
(otherwise 
(format nil " =:<(=a=)" number) )) 
may) 2) 
(title (if title 
(format nil "~:(~a~) " title) 
E) 
(format nil "~a~: (~a~)~a" title name number))) 
WARNING: redefining COMMON-LISP-USER::SAY-PERSON in DEFUN 
SAY- PERSON 
CL-USER> (say-person "john doe" :number 1 :roman-number nil) ¡thats better 
"John Doe the First" 
CL-USER> (say-person "louis" :title "king" :number 16 :roman-number nil) 
"King Louis the Sixteenth" 
CL-USER> (say-person "louis" :title "king" :number 16 :roman-number t) 
sia] bouis WiU 
CL-USER> (defun hello (&optional (name "World") &rest arguments) ;now we will just 
(apply #'hello-name name arguments)) ;pass all arguments to hello-name 
WARNING: redefining COMMON-LISP-USER::HELLO in DEFUN 
HELLO 
CL-USER> (defun hello-name (name &rest arguments) ;which will now just use 
(format t "Hello, ~a!" (apply #'say-person name arguments))) ;say-person 
WARNING: redefining COMMON-LISP-USER::HELLO-NAME in DEFUN 
HELLO-NAME 
CL-USER> (hello "louis" :title "king" :number 16) ¿this works now 
Hello, King Louis XVI! 
NIL 
CL-USER> 

















This highlights some of the advanced features of Common Lisp'S format function as well as some 
features like optional parameters and keyword arguments (e.g. :number). This also gives an 
example of interactive development at a REPL in common lisp. 

The simple Hello World program in REPL 


Common Lisp REPL is an interactive environment. Every form written after the prompt is 
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evaluated, and its value is afterwards printed as result of the evaluation. So the simplest possible 
“Hello, World!” program in Common Lisp is: 





CL-USER> "Hello, World!" 
"Hello, World!" 
CL-USER> 











What happens here is that a string costant is given in input to the REPL, it is evaluated and the 
result is printed. What can be seen from this example is that strings, like numbers, special symbols 
like rz and T and a few other literals, are self-evaluating forms: that is they evaluate to 
themselves. 

Basic expressions 


Let's try some basic expression in the REPL: 


USER ZE!) 





musings (SA) 





3) 





Com 





Qe ail area Dn © 
| 
E 
n 
A 
ve) 
Vv 
| 

















MUSA (tp S55 (= BS 2) (© 2 2) 

O63 

USER> (concatenate 'string "Hello, " "World!") 
Wake ILIL@,, morile 
CL-USER> 





The basic building block of a Common Lisp program is the form. In these examples we have 
functions forms, that is expressions, written as list, in which the first element is an operator (or 
function) and the rest of the elements are the operands (this is called “Prefix Notation”, or “Polish 
Notation”). Writing forms in the REPL causes their evaluation. In the examples you can see simple 
expressions whose arguments are constant numbers, strings and symbols (in the case of 'string, 
which is the name of a type). You can also see that arithmetic operators can take any number of 
arguments. 


It is important to note that parentheses are an integral part of the syntax, and cannot be used 
freely as in other programming languages. For instance the following is an error: 


Ge S (Gr 2 4))) 
> Error: Car of ((+ 2 4)) is not a function name or lambda-expression. ... 





In Common Lisp forms can also be data, symbols, macro forms, special forms and lambda forms. 
They can be written to be evaluated, returning zero, one, or more values, or can be given in input 
to a macro, that transform them in other forms. 


Sum of list of integers 


(defun sum-list-integers (list) 
(reduce '+ list)) 


https://riptutorial.com/ 6 


p LO 
(sum-list-integers '(1 2 3 4)) 


ES 
(Sumelist=imeeccezs "(il 23 4 § 6 7 &  i@)))) 


Lambda Expressions and Anonymous Functions 


An anonymous function can be defined without a name through a Lambda Expression. For 
defining these type of functions, the keyword 1ambaa is used instead of the keyword defun. The 
following lines are all equivalent and define anonymous functions which output the sum of two 
numbers: 


(lambda (x y) (+ x y)) 
(function (lambda (x y) (+ x y))) 
#' (lambda (x y) (+ x y)) 


Their usefulness is noticeable when creating Lambda forms, i.e. a form that is a list where the first 
element is the lambda expression and the remaining elements are the anonymous function's 
arguments. Examples (online execution): 


(rime (Maida EY (zw) 1 2)) ¢ SS 3 


(rime (map ec amo a (s a) Gr x wy) "CL 2 3) § (2 -5 O))) p >> (3 =s 3) 


Common Lisp Learning Resources 


Online Books 
These are books that are freely accessible online. 


e Practical Common Lisp by Peter Seibel is a good introduction to CL for experienced 
programmers, which tries to highlight from the very beginning what makes CL different to 
other languages. 

e Common Lisp: A Gentle Introduction to Symbolic Computation by David S. Touretzky is a 
good introduction for people new to programming. 

e Common Lisp: An interactive approach by Stuart C. Shapiro was used as a course textbook, 
and course notes accompany the book on the website. 

e Common Lisp, the Language by Guy L. Steele is a description of the Common Lisp 
language. According to the CLiki it is outdated, but it contains better descriptions of the loop 
macro and format than the Common Lisp Hyperspec does. 

e On Lisp by Paul Graham is a great book for intermediately experienced Lispers. 

e Let Over Lambda by Doug Hoyte is an advanced book on Lisp Macros. Several people 
recommended that you be comfortable with On Lisp before reading this book, and that the 
start is slow. 


Online References 
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e The Common Lisp Hyperspec is the language reference document for Common Lisp. 

e The Common Lisp Cookbook is a list of useful Lisp recipes. Also contains a list of other 
online sources of CL information. 

e Common Lisp Quick Reference has printable Lisp reference sheets. 

e Lispdoc.com searches several sources of Lisp information (Practical Common Lisp, 
Successful Lisp, On Lisp, the HyperSpec) for documentation. 

e Lisp.org is a redirect service for documentation. 


Offline Books 
These are books that you'll likely have to buy, or lend from a library. 


e ANSI Common Lisp by Paul Graham. 

e Common Lisp Recipes by Edmund Weitz. 

e Paradigms of Artificial Intelligence Programming has many interesting applications of Lisp, 
but is not a good reference for Al any more. 


Online Communities 


e The CLiki has a great Getting Started Page. A great resource for all things CL. Has an 
extensive list of Lisp books. 

e Common Lisp subreddit has loads of useful links and reference documents in the sidebar. 

e IRC: #lisp, #ccl, #sbcl and others on Freenode. 

e Common-Lisp.net provides hosting for many common lisp projects and user groups. 


Libraries 


e Quicklisp is library manager for Common Lisp, and has a long list of supported libraries. 

e Quickdocs hosts library documentation for many CL libraries. 

e Awesome CL is a community-driven curated list of libraries, frameworks and other shiny stuff 
sorted by category. 


Pre-packaged Lisp Environments 


These are Lisp editing environments that are easy to install and get started with because 
everything you need is pre-packaged and pre-configured. 


e Portacle is a portable and multiplatform Common Lisp environment. It ships a slightly 
customized Emacs with Slime, SBCL (a popular Common Lisp implementation), Quicklisp 
and Git. No installation needed, so it's a very quick and easy way to get going. 

e Lisobox is an IDE (Emacs + SLIME), Common Lisp environment (Clozure Common Lisp) 
and library manager (Quicklisp), pre-packaged as archives for Windows, Mac OSX and 
Linux. Descendant of "Lisp in a Box" Recommended in the Practical Common Lisp book. 

e Not pre-packed, but SLIME turns Emacs into a Common Lisp IDE, and has a user manual to 
help you get started. Requires a separate Common Lisp implementation. 


Common Lisp Implementations 


This section lists some common CL implementations and their manuals. Unless otherwise noted, 
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these are free software implementations. See also the Cliki's list of free software Common Lisp 
Implementations, and Wikipedia's list of commercial Common Lisp Implementations. 


* Allegro Common Lisp (ACL) and manual. Commercial, but has a free Express Edition and 
training videos on Youtube. 

e CLISP and manual. 

* Clozure Common Lisp (CCL) and manual. 

Carnegie Mellon University Common Lisp (CMUCL), has a manual and other useful 

information page. 

Embeddable Common Lisp (ECL) and manual. 

* LispWorks and manual. Commercial, but has a Personal Edition with some limitations. 

* Steel Bank Common Lisp (SBCL) and manual. 

Scieneer Common Lisp (SCL) and manual is a commercial Linux and Unix implementation, 

but has an unrestricted free evaluation and non-commercial use version. 


Read Getting started with common-lisp online: https://riptutorial.com/common- 
lisp/topic/534/getting-started-with-common-lisp 
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Chapter 2: ANSI Common Lisp, the language 
standard and its documentation 


Examples 


Common Lisp HyperSpec 


Common Lisp has a standard, which was initially published in 1994 as an ANSI standard. 


The Common Lisp HyperSpec, short CLHS, provided by LispWorks is an often used HTML 
documentation, which is derived from the standard document. The HyperSpec can also be 
downloaded and locally used. 


Common Lisp development environments usually allow lookup of the HyperSpec documentation 
for Lisp symbols. 


* For GNU Emacs there is clhs.el. 
¢ SLIME for GNU Emacs provides a version of hyperspec.el. 


See also: cliki on CLHS 


EBNF syntax declarations in documentation 


The ANSI CL standard uses an extended EBNF syntax notation. The documentation duplicated on 


Stackoverflow should use the same syntax notation to reduce confusion. 


Example: 





specialized-lambda-list::= 








({var | (var parameter-specializer-name))* 
é&éo0ptional {var | (var [initform [supplied-p-parameter] ]))*] 
£rest var] 
é&key{var | ({var | (keywordvar)} [initform [supplied-p-parameter] ]))* 
[Sallow-other-keys] ] 
Gawes {var | (var [initform] )}*] ) 
Notation: 


* [foo] -> Zero Or ONE foo 

e {foo}* -> Zero or More foo 

* foo | bar ->foo OF bar 
Common Lisp the Language, 2nd Edition, by Guy L. Steele Jr. 
This book is known as CLtL2. 


This is the second edition of the book Common Lisp the Language. It was published in 1990, 
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before the ANSI CL standard was final. It took the original language definition from the first edition 
(published in 1984) and described all changes in the standardization process up to 1990 plus 
some extensions (like the SERIES iteration facility). 


Note: CLTL2 describes a version of Common Lisp which is slightly different from the 
published standard from 1994. Thus always use the standard, and not CLtL2, as a 
reference. 


CLtL2 still can be useful, because it provides information not found in the Common Lisp 
specification document. 


There is a HTML version of Common Lisp the Language, 2nd Edition. 
CLiki - Proposed ANSI Revisions and Clarifications 


On CLiki, a Wiki for Common Lisp and free Common Lisp software, a list of Proposed ANS! 
Revisions and Clarifications is being maintained. 


Since the Common Lisp standard has not changed since 1994, users have found several 
problems with the specification document. These are documented on the CLiki page. 


Common Lisp Quick Reference 


The Common Lisp Quick Reference is a document which can be printed and bound as a booklet in 
various layouts to have a printed quick reference for Common Lisp. 


The ANSI Common Lisp standard in Texinfo format (especially useful for GNU 
Emacs) 


GNU Emacs uses a special format for documentation: info. 


The Common Lisp standard has been converted to the Texinfo format, which can be used to 
create documentation browsable with the info reader in GNU Emacs. 


See here: dpans2texi.el converts the TeX sources of the draft ANSI Common Lisp standard 
(dpANS) to the Texinfo format. 


Another version has been done for for GCL: gcl.info.tgz. 


Read ANSI Common Lisp, the language standard and its documentation online: 
https://riptutorial.com/common-lisp/topic/2900/ansi-common-lisp--the-language-standard-and-its- 
documentation 


https://riptutorial.com/ 11 


Chapter 3: ASDF - Another System Definition 
Facility 


Remarks 


ASDF - Another System Definition Facility 


ASDF is a tool for specifying how systems of Common Lisp software are made up of components 
(sub-systems and files), and how to operate on these components in the right order so that they 
can be compiled, loaded, tested, etc. 


Examples 


Simple ASDF system with a flat directory structure 
Consider this simple project with a flat directory structure: 


example 

|-- example.asd 
|== functions, Lisp 
|== meata disg 

|-- packages.lisp 
ESO ES AE ES O 


The example. asa file is really just another Lisp file with little more than an ASDF-specific function 
call. Assuming your project depends on the arakma and cisqi systems, its contents can be 
something like this: 


(asdf:defsystem :exampl 








:description "a simpl xample project" 
:version "1.0" 

:author "TheAuthor" 

:depends-on (:clsql 


:drakma) 

:components ((:file "packages") 
(:file "tools" :depends-on ("packages") ) 
(:file "functions" :depends-on ("packages") ) 
Cs 


file "main" :depends-on ("packages" 
MseoUMeIe erm) IN 


When you load this Lisp file, you tell ASDF about your :examp1e system, but you're not loading the 
system itself yet. That is done either by (asdf:require-system :example) Of (ql:quickload :example). 





And when you load the system, ASDF will: 


1. Load the dependencies - in this case the ASDF systems cisqi and drakma 
2. Compile and load the components of your system, i.e. the Lisp files, based on the given 
dependencies 
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— 


. packages first (no dependencies) 

2. functions after packages (as it only depends on packages), but before main (which 
depends on it) 

3. main after functions (as it depends ON packages and functions) 

4. tools anytime after packages 


Keep in mind: 


+ Enter the dependencies as they are needed (e.g. macro definitions are needed before 
usage). If you don't, ASDF will error when loading your system. 

e All files listed end on .1isp but this postfix should be dropped in the asdf script 

* If your system is named the same as its .asa file, and you move (or symlink) its folder into 
quicklisp/local-projects/ folder, you can then load the project using (ql:quickload 
"example"). 

e Libraries your system depends on have to be known to either ASDF (via the aspr: *cenTRAL- 

REGISTRY Variable) or Quicklisp (either via the QUICKLISP-CLIENT : *LOCAL-PROJECT-DIRECTORIES* 

variable or available in any of its dists) 





























How to define a test operation for a system 


(in-package #:asdf—-user) 


(defsystem +: foo 
«components ((:file "foo")) 
TiN Orde Om fals dire Sin OO as aio op 3100) np) 
:perform (asdf:test-op (o c) 
(uiop:symbol-call :foo-tests 'run-tests))) 


(defsystem #:foo-tests 
:name "foo-test" 
:components ((:file "tests"))) 





7; Afterwards to run the tests we type in the REPL 
(asdf :test-system :foo) 





Notes: 


e We are assuming that the system :foo-tests defines a package named "FOO-TESTS" 

e run-tests İS the entry point for the test runner 

* uoip:symbol-call allows as to define a method that calls a function that hasn't been read yet. 
The package the function is defined in doesn't exist when we define the system 


In what package should | define my ASDF system? 


ASDF provides the package aspr-user for developers to define their packages in. 





Read ASDF - Another System Definition Facility online: https://riptutorial.com/common- 
lisp/topic/670/asaf---another-system-definition-facility 
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Chapter 4: Basic loops 


Syntax 


(do ({var | (var [init-form [step-form]])}*) (end-test-form result-form*) declaration* {tag | 
statement}*) 

(do* ({var | (var [init-form [step-form]])}*) (end-test-form result-form*) declaration* {tag | 
statement}*) 

e (dolist (var list-form [result-form]) declaration* {tag | statement}*) 

e (dotimes (var count-form [result-form]) declaration* {tag | statement}*) 


Examples 


dotimes 


dotimes iS a macro for integer iteration over a single variable from 0 below some parameter value. 
One of the simples examples would be: 


CL-USER> (dotimes (i 5) 
(Pine) 





EII A 


NIL 


Note that rx is the returned value, since we did not provide one ourselves; the variable starts from 
0 and throughout the loop becomes values from 0 to N-1. After the loop, the variable becomes the 
N: 


CESUSER (domo SO) O) 














CL-USER> (defun O-to-n (n) 
MEMES C) 
(dotimes (i n (nreverse list)) 
(Pus ES Ii 
0-TO-N 
TUS OSO SO) 
(ORTE T) 





dolist 


dolist İs a looping macro created to easily loop through the lists. One of the simplest uses would 
be: 
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CL=USER> (dolist (item ‘(a bc d)) 
(print item) ) 





[Si YQ) lus) pe 


NIL ; returned value is NIL 


Note that since we did not provide return value, wr is returned (and A,B,C,D are printed to 


*standard-output*). 


dolist Can also return values: 


7;This may not be the most readable summing function. 
(defun sum-list (list) 
(let ( (sum 0)) 
(dolisete (Vos su) 
(incf sum var)))) 





CL-USER> (sum-list (list 2 3 4)) 


Simple loop 


The loop macro has two forms: the "simple" form and the "extended" form. The extended form is 
covered in another documentation topic, but the simple loop is useful for very basic loop. 


The simple loop form takes a number of forms and repeats them until the loop is exited using 
return or some other exit (e.g., throw). 


(Gew (2 0)) 
(Loop 
(Pri) 
(Mc) 
(unless (< x 5) 
(return)))) 


E JE V A g 


NIL 


Read Basic loops online: https://riptutorial.com/common-lisp/topic/2053/basic-loops 
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Chapter 5: Booleans and Generalized 
Booleans 


Examples 


True and False 


The special symbol t represents the value true in Common Lisp, while the special symbol wr 
represents false: 


CL-USER> (= 3 3) 














They are called “Constant Variables” (sic!) in the standard, since they are variables whose value 
cannot be modified. As a consequence, you cannot use their names for normal variables, like in 
the following, incorrect, example: 


CL-USER> (defun my-fun (t) 
(r e 1) 
While compiling MY-FUN : 
Cante brad! or assim co cOon's Pana 





Actually, one can consider them simply as constants, or as self-evaluated symbols. t and niu are 
specials in other senses, too. For instance, 1 is also a type (the supertype of any other type), while 
NTL is also the empty list: 














CL-USER> (eql NIL '()) 

TE 

CTE USER (COLS au (Ce Ons may omsa=aly))) 
(A B) 


Generalized Booleans 
Actually any value different from wrx is considered a true value in Common Lisp. For instance: 


CASERAS ((e (re 2 2)))))) 
(if a 
a 
OLEO vA ar 2 ie e QU CS ORT E) 





This fact can be combined with the boolean operators to make programs more concise. For 
instance, the above example is equivalent to: 
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¡CAUSE (or (a 2 2) YOla my! 2 a 2 ais eemell to NELY) 


The macro or evaluates its arguments in order from left to right and stops as soon as it finds a 
non-NIL value, returning it. If all of them are wr, the value returned is nit: 





CLAUSES (ee (= 1 2) (= 3 4) (© S &)) 
NIL 


Analogously, the macro ann evaluates its arguments from left to right and returns the value of the 
last, if all of them are evaluated to non-NIL, otherwise stops the evaluation as soon as it finds wrt, 
returning it: 


CL-USER> (let ((a 2) 








2/3 
CL-USER> (let ((a 2) 
(b 0)) 
(and (/= b 0) (/ a b))) 
NIL 


For these reasons, ann and or can be considered more similar to control structures of other 
languages, rather than to boolean operators. 


Read Booleans and Generalized Booleans online: https://riptutorial.com/common- 
lisp/topic/3292/booleans-and-generalized-booleans 
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Chapter 6: CLOS - the Common Lisp Object 
System 


Examples 


Creating a basic CLOS class without parents 


A CLOS class is described by: 


* aname 
e alist of superclasses 

a list of slots 

e further options like documentation 


Each slot has: 


* aname 
* an initialization form (optional) 

e an initialization argument (optional) 

e a type (optional) 

* a documentation string (optional) 

* accessor, reader and/or writer functions (optional) 
e further options like allocation 


Example: 


(defclass person () 





( (name 
SANCIONES "Erika Mustermann" 
galilea ¿name 
:type SHE TE ALIN 
:documentation "the name of a person" 
:accessor person-name) 
(age 
:initform 25 
niiae] :age 
:type number 


:documentation "the age of a person" 
:accessor person-age)) 
(:documentation "a CLOS class for persons with name and age")) 


A default print method: 


(defmethod print-object ((p person) stream) 
"The default print-object method for a person" 
(print-unreadable-object (p stream :type t :identity t) 





(with-slots (name age) p 
(format stream "Name: ~a, age: ~a" name age)))) 
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Creating instances: 


USER > 











USER > 








(make-instance 
ERSON Name: 


(make-instance 
ERSON Name: 





ax 


Erika Mustermann, 


'person) 
age: 25 4020169AB3> 
:name "Max Mustermann" 
24 4020169FEB> 


"person sage 24) 





Mustermann, age: 


Mixins and Interfaces 


Common Lisp does not have interfaces in the sense that some languages (e.g., Java) do, and 


there is less need for that type of interface given that Common Lisp supports multiple inheritance 


and generic functions. However, the same type of patterns can be realized easily using mixin 
classes. This example shows the specification of a collection interface with several corresponding 
generic functions. 


vr 


(defclass collection 


(:documen 


(defgeneric 
(:documen 


(defgeneric 


(: document 


(defgeneric 
(:documen 


(defgeneric 
(:documen 


(defmethod coll 
"default" 


"A 


List,” 
(endp 


ta 





Specification of the COLLECTION 


tion 


Winterkace™ 





O O 

WA Collection miosina H) 
tion-elements (collection) 

"Returns a list of the elements in the collection.")) 
tion-add (collection element) 

"Adds an element to the collection.")) 











tati 





lection-empty-p 
implementation of COLL 
whether the list returned by COLLEC 


tion-remov 
"Removes th 


lement) 
lement from the collection, 


(collection 





abit alice abs) PRESE ME) 





(collection) 
th 


tion-empty-p 
"Returns whether 





collection is empty or not.")) 


(Meco mc cto)» 
ECTION-EMPTY-P that tests 
ION-ELEMENTS is the empty 





























EM 





(collection-elements c))) 


An implementation of the interface is just a class that has the mixin as one of its super classes, 
and definitions of the appropriate generic functions. (At this point, notice that the mixin class is 
really only for signalling the intent that the class implements the "interface". This example would 
work just as well with a few generic functions and documentation that states that there are 
methods on the function for the class.) 


vr 


(defclass sorted-set 


( (predicate 


Implementation of a sorted-set class 


(collection) 


:initarg :predicate 





:reader sorted-set-predicate) 


(test 


:initarg 


A ikon 


{lest 
Teql 
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:reader sorted-set-test) 

(elements 

Jimeno Y (()) 

saccessor sorted-set-elements 

7; We can "implement" the COLLECTION-ELEMENTS function, that is, 
7; define a method on COLLECTION-ELEMENTS, simply by making it 
97 E readen (or acesssoz) or ae Slot, 









































¿reader collection-elements))) 


(defmethod collection-add ((ss sorted-set) element) 
(unless (member element (sorted-set-elements ss) 








:test (sorted-set-test ss)) 
(setf (sorted-set-elements ss) 
(merge 'list 
(list element) 
(sorted-set-elements ss) 
(sorted-set-predicate ss))))) 





(defmethod collection-remove ((ss sorted-set) element) 
(setf (sorted-set-elements ss) 
(delete element (sorted-set-elements ss)))) 


Finally, we can see what using an instance of the sorted-set class looks like when using the 
"interface" functions: 








(let ((ss (make-instance 'sorted-set :predicate '<))) 
(collection-add ss 3) 
collection-add ss 4) 
collection-add ss 5) 


( 

( 

(colllection=add ss 3) 
(collection-remove ss 5) 
( 


collection-elements ss)) 
fp == (8 4) 


Read CLOS - the Common Lisp Object System online: https://riptutorial.com/common- 
lisp/topic/673/clos---the-common-lisp-object-system 
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Chapter 7: CLOS Meta-Object Protocol 


Examples 


Obtain the slot names of a Class 
Lets say we have a class as 


(defclass person () 
(name email age)) 


To obtain the names of the slots of the class we use the function class-slots. This can be found in 
the closer-mop package, provided by the closer-mop system. To load it the running lisp image we 


USE (ql:quickload :closer-mop). We also have to make sure the class is finalized before calling 
class-slots. 


(let ((class (find-class 'person) ) ) 
(c2mop:ensure-finalized class) 
(c2mop:class-slots class) ) 


which returns a list of effective slot definition objects: 





(#<SB-MOP : STANDARD-EFFECTIVE-SLOT-DEFINITION S/TRANSFORMATIONS: : NAME> 
#<SB-MOP : STANDARD-EFFECTIVE-S EFINITION S/TRANSFORMATIONS: :EMAIL> 
#<SB-MOP : STANDARD-EFFECTIVE-SLOT-DEFINITION S/TRANSFORMATIONS: :AGE>) 














© 
l 
z 















































Update a slot when another slot is modified 


The CLOS MOP provides the hook slot-value-using-class, that is called when a slot is value is 
accessed, read or modified. Because we only care for modifications in this case we define a 
method for (setf slot-value-using-class). 


(defclass document () 
((id :reader id :documentation "A hash computed with the contents of every other slot") 
(esicle simbrcaro stlele saceassor elele) 
(body :initarg :body :accessor body))) 


(defmethod (setf c2mop:slot-value-using-class) :after 





(new class (object document) (slot c2mop:standard-effective-slot-definition)) 
7; To avoid this method triggering a call to itself, we check that the slot 
77 the modification occurred in is not the slot we are updating. 
(unless (eq (slot-definition-name slot) 'id) 

(setf (slot-value object 'id) (hash-slots object)))) 





Note that because at instance creation s10t-value is not called it may be necessary to duplicate 
the code in the initialize-instance :after method 


(defmethod initialize-instance :after ((obj document) €key) 
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(setf (slot-value obj 'id) 
(hash-slots ob3))) 


Read CLOS Meta-Object Protocol online: https://riptutorial.com/common-lisp/topic/2901/clos- 
meta-object-protocol 
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Chapter 8: Cons cells and lists 


Examples 


Lists as a convention 


Some languages include a list data structure. Common Lisp, and other languages in the Lisp 
family, make extensive use of lists (and the name Lisp is based on the idea of a LISt Processor). 
However, Common Lisp doesn't actually include a primitive list datatype. Instead, lists exist by 
convention. The convention depends on two principles: 


1. The symbol nil is the empty list. 
2. Anon empty list is a cons cell whose car is the first element of the list, and whose car is the 
rest of the list. 


That's all that there is to lists. If you've read the example called What is a cons cell?, then you 
know that a cons cell whose car is X and whose cdr is Y can be written as (X . Y). That means that 
we can write some lists based on the principles above. The list of the elements 1, 2, and 3 is 
simply: 


However, because lists are so common in the Lisp family of languages, there are special printing 
conventions beyond the simple dotted pair notation for cons cells. 


1. The symbol nil can also be written as (). 
2. When the cdr of one cons cell is another list (either () or a cons cell), instead of writing the 
one cons cell with the dotted pair notation, the "list notation" is used. 


The list notation is shown most clearly by several examples: 


The idea is that the elements of the list are written in successive order within parenthesis until the 
final cdr in the list is reached. If the final cdr is nil (the empty list), then the final parenthesis is 
written. If the final cdr is not nil (in which case the list is called an improper list), then a dot is 
written, and then that final cdr is written. 


What is a cons cell? 
A cons cell, also known as a dotted pair (because of its printed representation), is simply a pair of 


two objects. A cons cell is created by the function cons, and elements in the pair are extracted 
using the functions car and car. 
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(cons "a" 4) 


For instance, this returns a pair whose first element (which can be extracted with car) is "a", and 
whose second element (which can be extracted with car), is 4. 


(Gar (cons “a” 41) 
pp=> "a" 


(Cori COnS ea) 
P= 3 


Cons cells can be printed in dotted pair notation: 


(cons LT) 
p5=> (E o 2) 


Cons cells can also be read in dotted pair notation, so that 


Car Vz sein) 
=> X 
car Me s 5) 
AS 


(The printed form of cons cells can be a bit more complicated, too. For more about that, see the 
example about cons cells as lists.) 


That's it; cons cells are just pairs of elements created by the function cons, and the elements can 
be extracted with car and car. Because of their simplicity, cons cells can be a useful building block 
for more complex data structures. 


Sketching cons cells 


To better understand the semantics of conses and lists, a graphical representation of this kind of 
structures is often used. A cons cell is usually represented with two boxes in contact, that contain 
either two arrows that point to the car and car values, or directly the values. For instance, the 
result of: 


(eon. 
pp == (Ll « 8) 


can be represented with one of these drawings: 
oe 2 ge 
1 1 2 


Note that these representations are purely conceptual, and do not denote the fact that the values 
are contained into the cell, or are pointed from the cell: in general this depends on the 
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implementation, the type of the values, the level of optimization, etc. In the rest of the example we 
will use the first kind of drawing, which is the one more commonly used. 


So, for instance: 


(comas l lecons 2 (cons 3 4i ; improper “dotted” list 
fp => (1 28 o 4) 


is represented as: 
ee 4 
1 2 3 


while: 


(cons l (cons 2 (cons 3 (SOSA in) np) ap proper list, esuivalene eos (ise 1 2 3 4) 
pp => (1 2 3 4) 


is represented as: 
1 2 


Here is a tree-like structure: 


(cons (cons Lie (cons 3 241) 
pp => (ML. 2) S » A) ; note the printing as an improper list 


The final example shows how this notation can help us to understand important semantics aspects 
of the language. First, we write an expression similar to the previous one: 


(cons (cons L 2) cons L 2) 
PR => A o IS) 


that can be represented in the usual way as: 
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Then, we write a different expression, which is apparently equivalent to the previous one, and this 
seems confirmed by printed representation of the result: 


(let ((cell=a (cons 1 2))) 
(cons cell-a cell-a)) 
ra => (L a 2) 2 a 2) 


But, if we draw the diagram, we can see that the semantics of the expression is different, since the 
same cell is the value both of the car part and the car part of the outer cons (this is, ce11-a İS 
shared): 


and the fact that the semantics of the two results is actually different at the language level can be 
verified by the following tests: 


(Let Miel (cons icons L 2) (cons L Zi) 
lez (lee (leell=a eons 1 211) 
(cons cell-a cell-a)))) 


(Lise (es (Gar ci) (ele ei) 
(ea (eaz e2) (cci 2100) 
NT 


The first eq is false since the car and car of ci are structurally equal (that is true by equa1), but are 
not “identical” (i.e. “the same shared structure”), while in the second test the result is true since the 
car and car Of c2 are identical, that is they are the same structure. 


Read Cons cells and lists online: https://riptutorial.com/common-lisp/topic/2622/cons-cells-and- 
lists 
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Chapter 9: Control Structures 


Examples 


Conditional Constructs 





In Common Lisp, i£ is the simplest conditional construct. It has the form (if test then [else]) and 
is evaluated to then if test is true and else otherwise. The else part can be omitted. 


(aie (> 3 2) 
"Three is bigger!" 





"Two is bigger!") 
77=> "Three is bigger!" 


One very important difference between i£ in Common Lisp and i£ in many other programming 
languages is that CL's i£ is an expression, not a statement. As such, i£ forms return values, which 
can be assigned to variables, used in argument lists, etc: 


7; Use a different format string depending on the type of x 
(format t (if (numberp x) 


Wogan gm 


"~a~g") 


x) 


Common Lisp's i£ can be considered equivalent to the ternary operator ?: in C# and other "curly 
brace" languages. 


For example, the following C# expression: 
year == 1990 ? "Hammertime" : "Not Hammertime" 

Is equivalent to the following Common Lisp code, assuming that year holds an integer: 
(if (eql year 1990) "Hammertime" "Not Hammertime") 


cond İs another conditional construct. It is somewhat similar to a chain of i£ statements, and has 
the form: 





(cond (test-1 consequent-1-1 consequent-2-1 ...) 
(test-2) 
(test-3 consequent-3-1 ...) 
) 





More precisely, cona has zero or more clauses, and each clause has one test followed by zero or 
more consequents. The entire cona construct selects the first clause whose test does not evaluate 
to ni1 and evaluates its consequents in order. lt returns the value of the last form in the 
consequents. 
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"Three is bigger than four!") 
"Three is bigger than three!") 
"Three is bigger than two!") 


BES ES ls 





"Three is bigger than one!")) 
ree is bigger than two!" 


To provide a default clause to evaluate if no other clause evaluates to +, you can add a clause that 
is true by default using +. This is very similar in concept to SQL's casz...eLse, but it uses a literal 
boolean true rather than a keyword to accomplish the task. 

















(Copa 
((= n 1) "N equals 1") 
(t "N doesn't equal 1") 


An i£ construct can be written as a cona construct. (if test then else) ANG (cond (test then) (t 
else)) are equivalent. 


If you only need one clause, USe when OF unless: 


(when (> 3 4) 
"Three is bigger than four.") 
¡=> NIL 


(when (< 2 5) 
"Two is smaller than five.") 


OS ES co 


(unless (> 3 4) 
Three is bigger than four.") 
¡=> "Three is bigger than four." 


(UMSS (ZAS) 
Two is smaller than five.") 
;;=> NIL 





The do loop 


Most looping and conditional constructs in Common Lisp are actually macros that hide away more 
basic constructs. For example, dotimes and dolist are built upon the ao macro. The form for ao 
looks like this: 


(do (varlist) 
(endlist) 
&body) 


* varlist is composed of the variables defined in the loop, their initial values, and how they 
change after each iteration. The 'change' portion is evaluated at the end of the loop. 

e enalist contains the end conditions and the values returned at the end of the loop. The end 
condition is evaluated at the beginning of the loop. 


Here's one that starts at 0 and goes upto (not including) 10. 
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¡same as (dotimes (i 10)) 
(COM 5) 
Mé 1 10) 1) 
(PESE 


And here's one that moves through a list: 


;;same as (dolist (item given-list) 
(do ((item (car given-list) ) 
(temp list (cdr temp) ) 
(print item) ) 


The variist portion is similar the one in a 1er statement. You can bind more than one variable, and 
they only exist inside the loop. Each variable declared is in its own set of parenthesis. Here's one 
that counts how many 1's and 2's are in a list. 


(let (vars (lisit 1 2 3 2 2 1))) 
(do ((ones 0) 
(twos 0) 
(temp vars (cdr temp) ) ) 
((not temp) (list ones twos) ) 
(when (= (car temp) 1) 
(setf ones (+ 1 ones)) ) 
(when (= (car temp) 2) 
(setf twos (+ 1 twos))))) 
=> (2 3) 





And if a while loop macro hasn't been implemented: 


(do () 
(t) 
(when task-done 
(break) ) ) 


For the most common applications, the more specific aot imes and doloop Macros are much more 
succinct. 


Read Control Structures online: https://riptutorial.com/common-lisp/topic/3229/control-structures 
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Chapter 10: Creating Binaries 


Examples 


Building Buildapp 


Standalone Common Lisp binaries can be built with buiicapp. Before we can use it to generate 
binaries, we need to install and build it. 


The easiest way | know how is using quickiisp and a Common Lisp (this example uses [sbc1], but 
it shouldn't make a difference which one you've got). 


E abel 


This is SBCL 1.3.5.nixos, an implementation of ANSI Common Lisp. 
More information about SBCL is available at <http://www.sbcl.org/>. 


SBCL is free software, provided as is, with absolutely no warranty. 
It is mostly in the public domain; some portions are provided under 
BSD-style licenses. S the CREDITS and COPYING files in the 


distribution for more information. 








* (ql:quickload :buildapp) 
to losa “Moa lega" 

Load 1 ASDF system: 
buildapp 





; Loading "buildapp" 
(:BUILDAPP) 


* (buildapp:build-buildapp) 

;; loading system "buildapp" 

[undoing binding stack and other enclosing state... done] 
[saving current Lisp image into /home/inaimathi/buildapp: 
writing 4800 bytes from the read-only space at 0x20000000 
writing 3216 bytes from the static space at 0x20100000 
writing 47349760 bytes from the dynamic space at 0x1000000000 
done] 

NIL 


(CUESTE) 
S ls -1h buildapp 


—rwxr-xr-x 1 inaimathi inaimathi 46M Aug 13 20:12 buildapp 
$ 


Once you have that binary built, you can use it to construct binaries of your Common Lisp 


programs. If you intend to do this a lot, you should also probably put it somewhere on your park SO 
that you can just run it with buiidapp from any directory. 


Buildapp Hello World 


The simplest possible binary you could build 
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1. Has no 


dependencies 


2. Takes no command line arguments 


3. Just wri 


tes "Hello world!" to stdout 


After you've built buiidapp, you Can just... 


$ buildapp - 
-entry main 
[undoing bin 
[saving curr 
writing 4800 
writing 3216 
writing 4322 
done] 


$ ./hello-wo 
Hello, world 


$ 


-eval '(defun main (argv) (declare (ignore argv)) (write-line "Hello, world!"))' - 


—-output hello-world 

ding stack and other enclosing state... done] 

ent Lisp image into hello-world: 

bytes from the read-only space at 0x20000000 
bytes from the static space at 0x20100000 

0992 bytes from the dynamic space at 0x1000000000 


ie lll 


Buildapp Hello Web World 


A more realistic example involves a project you're building with multiple files on disk (rather than 


an --eva1 opti 


on passed to buildapp), and some dependencies to pull in. 


Because arbitrary things can happen during the finding and loading Of asas systems (including 
loading other, potentially unrelated systems), it's not enough to just inspect the asa files of the 


projects you'r 


e depending on in order to find out what you need to load. The general approach is 





tO USE quicklisp to load the target system, then call qi:write-asdf-manifest-file to write out a full 
manifest of everything that's loaded. 


Here's a toy system built with hunchentoo+ to illustrate how that might happen in practice: 











7777 buildapp-hello-web-world.asd 


(asdf :defsys 
:descripti 


tem #:buildapp-hello-web-world 
on "An example application to use when getting familiar with buildapp" 


:author "inaimathi <leo.zovic@gmail.com>" 





:license "Expat" 


:depends-on (#:hunchentoot) 


costeras ic 
: component 


rrrr package 


(defpackage 
(:use #:cl 





s ((:file "package") 

(:file "buildapp-hello-web-world")) 
alise 
#:buildapp-hello-web-world 


#:hunchentoot) ) 


7777 buildapp-hello-web-world.lisp 


(in-package #:buildapp—hello-—web-world) 
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(defin ashy—ineincllee (Mello sur "/) () 
(setf (hunchentoot:content-type*) "text/plain") 
"Hello Web World!") 








(defun main (argv) 
(declare (ignore argv)) 
(start (make-instance 'easy-acceptor :port 4242)) 
(format t "Press any key to exit...-%") 
(read-char)) 


ppp ocio Liso 
(ql:quickload :buildapp-hello-web-world) 
(q1:write-asdf-manifest-file "/tmp/build-hello-web-world.manifest") 





(with-open-file (s "/tmp/build-hello-web-world.manifest" :direction :output :if-exists 
:append) 
(format s "~a~%S" (merge-pathnames 


"buildapp-hello-web-world.asd" 





(asdf /system:system-source-directory 
:buildapp-hello-web-world)))) 


#### build.sh 
sbel ==leae. “emi lel, Lisp“ =cut 








buildapp manifest-file /tmp/build-hello-web-world.manifest load-system hunchentoot load 
system buildapp-hello-web-world output hello-web-world ntry buildapp-hello-web-world:main 

















Once you have those files saved in a directory named buiidapp-hello-web-world, you Can do 


$ cd buildapp-hello-web-world/ 


$ sh build.sh 
This is SBCL 1.3.7.nixos, an implementation of ANSI Common Lisp. 
More information about SBCL is available at <http://www.sbcl.org/>. 


SBCL is free software, provided as is, with absolutely no warranty. 
It is mostly in the public domain; some portions are provided under 
BSD-style licenses. S the CREDITS and COPYING files in the 
distribution for more information. 

To Loge Verris 

Load 1 ASDF system: 

CEEL 

p Loading Vorri” 








To load "buildapp-hello-web-world": 
Load 1 ASDF system: 
buildapp-hello-web-world 





; Loading "buildapp-hello-web-world" 


O ACCESS Sn 

7; loading system "hunchentoot" 

7; loading system "buildapp-hello-web-world" 

[undoing binding stack and other enclosing state... done] 
[saving current Lisp image into hello-web-world: 

writing 4800 bytes from the read-only space at 0x20000000 
writing 4624 bytes from the static space at 0x20100000 
writing 66027520 bytes from the dynamic space at 0x1000000000 
done] 
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$ ls -1h hello-web-world 
-rwxr-xr-x 1 inaimathi inaimathi 64M Aug 13 21:17 hello-web-world 





This produces a binary that does exactly what you think it should, given the above. 


$ ./hello-web-world 
Press any key to exit... 


You should then be able to fire up another shell, do cur1 localhost :4242 and see the plaintext 


response Of Hello web Wor1a! get printed out. 


Read Creating Binaries online: https://riptutorial.com/common-lisp/topic/5457/creating-binaries 
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Chapter 11: Customization 


Examples 


More features for the Read-Eval-Print-Loop (REPL) in a terminal 


CLISP has an integration with GNU Readline. 


For improvements for other implementations see: How to customize the SBCL REPL. 
Initialization Files 


Most Common Lisp implementations will try to load an init file on startup: 

















ABCL SHOME/.abclre 

Allegro CL SHOME/.clinit.cl 

ECL SHOME / .eclrc 

Clasp SHOME/.clasprc 

CLISP SHOME/.clisprc.lisp 

Clozure CL home:ccl-init.lisp Ol home:ccl-init.fasl Or 


home: .ccl-init.lisp 





CMUCL SHOME / .cmucl-init.lisp 

LispWorks SHOME / . lispworks 

MKCL SHOME/ .mkclrc 

SBCL SHOME/.sbclre $SBCL_HOME/sbclrc OY 
/etc/sbclre 

SCL SHOME/.scl-init.lisp 

















Sample Initialization files: 


Implementation | Sample Init file 


LispWorks Library/lib/7-0-0-0/config/a-dot-lispworks. lisp 
Optimization settings 
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Common Lisp has a way to influence the compilation strategies. It makes sense to define your 
preferred values. 


Optimization values are between 0 (unimportant) and 3 (extremely important). 1 is the neutral 
value. 


It's useful to always use safe code (safety = 3) with all runtime checks enabled. 


Note that the interpretation of values is implementation specific. Most Common Lisp 
implementations make some use of these values. 





: useful default useful delivery 
Explanation 
value value 
compilation- speed of the compilation 2 0 
speed process 
debug ease of debugging 2 toro 
safety run-time error checking 3 2 
both code size and run-time 
space 2 2 
space 
speed speed of the object code 2 3 


An optimize declaration for use with declaim, declare and proclaim: 


(optimize (compilation-speed 2) 


( 

(debug 2) 
(safety 3) 
(space 2) 
(speed 2)) 


Note that you can also apply special optimization settings to portions of the code in a function 
using the macro tocatty. 


Read Customization online: https://riptutorial.com/common-lisp/topic/5679/customization 
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Chapter 12: Equality and other comparison 
predicates 


Examples 


The difference between EQ and EQL 


1. zo checks if two values have the same address of memory: in other words, it checks if the 
two values are are actually the same, identical object. So, it is can be considered the identity 
test, and should be applied only to structures: conses, arrays, structures, objects, typically to 
see if you are dealing in fact with the same object “reached” through different paths, or 
aliased through different variables. 





2. zoL Checks if two structures are the same object (like =o) or if they are the same non- 
structured values (that is, the same numeric values for numbers of the same type or the 
character values). Since it includes the zo operator and can be used also on non-structured 
values, is the most important and most commonly used operator, and almost all the primitive 
functions that require an equality comparison, like memser, use by default this operator. 























So, it is always true that (zo x y) implies (zon x y), while the viceversa does not hold. 








A few examples can clear the difference between the two operators: 











(SACA) 
T ;; => since two s-expressions (QUOTE A) are “internalized” as the same symbol by the reader. 
(eeg (ist e) (Lise “a)) 
NIL ;; => here two lists are generated as different objects in memory 
MEA (ii (list tan) 
(12 LLY) 
(ss 11 12)) 
T ;; => here there is only one list which is accessed through two different variables 
(SALSAS) 
22 ;; it depends on the implementation: it could be either T or NIL if integers are “boxed” 
(eq #\a #\a) 
272 ;; it depends on the implementation, like for numbers 
(eq 2d0 2d0) 
272 77 => dependes on the implementation, but usually is NIL, since numbers in double 
a precision are treated as structures in many implementations 
(let ((al 2d0) 
(a2 2d0)) 
(eq al a2)) 
2? ;; => also in this case the results depends on the implementation 


Let's try the same examples with cot: 





(eql 'a 'a) 








T ;; => equal because they are the same value, as for EQ 

(SAS “al AS Sa) 

NIL ;; => different because they different objects in memory, as for EQ 
(let* ((11 (list 'a)) 
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(12 LLJ) 
(Co a) 
[ ;; => as above 
(eql 1 1) 
T ;; they are the same number, ven if integers are “boxed” 
(eql #\a #\a) 
T ;; they are the same character 


(eql 2d0 2d0) 


T ;; => they are the same number, even if numbers in double precision are treated as 

















PE structures in many implementations 
(let ((al 2d0) 
(a2 2d0)) 
(eql al a2)) 
T ;; => as before 
(eql 2 2.0) 
NIL;; => since the two values are of a different numeric type 





From the examples we can see why the zon operator should be used to portably check for 
“sameness” for all the values, structured and non-structured, and why actually many experts 


advise against the use of zo in general. 





Structural equality with EQUAL, EQUALP, TREE-EQUAL 


These three operators implement structural equivalence, that is they check if different, complex 
objects have equivalent structure with equivalent component. 


zovaL behaves like cox for non-structured data, while for structures built by conses (lists and trees), 
and the two special types of arrays, strings and bit vectors, it performs structural equivalence, 
returning true on two structures that are isomorphic and whose elementary components are 
correspondingly equal by zouar. For instance: 











(equal (lise L feoms 2 3)))) (last 1 (eons 2 (a 2 1I) 

77 => since the two arguments are both equal to (1 (2 . 3)) 
(equal "ABC" "ABC") 

> Esuieuliiey dla Seines 

(equal "Abc" "ABC") 

NIL ;; => case sensitiv quality on strings 




















(EUA A AE UA AE CU) 
T ;; => equal since it uses EQL on 1 and 1, and EQUAL on "ABC" and "ABC" 
(let* ((a (make-array 3 :initial-contents '(1 2 3))) 

(io (male=arzeay 3 3imbrlcl=comeents “(i 2 3))) 

(e a) 


(values (equal a b) 
(equal a c))) 
NIL ;; => the structural equivalence is not used for general arrays 
T 77 => a and c are alias for the same object, so it is like EQL 











zouarP returns true on all cases in which zova is true, but it uses also structural equivalence for 
arrays of any kind and dimension, for structures and for hash tables (but not for class instances!). 
Moreover, it uses case insensitive equivalence for strings. 


(equalp "Abc" "ABC") 
T ;; => Case insensitiv quality on strings 





(equalp (make-array 3 :initial-contents '(1 2 3)) 
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(makes array 3 simitclicu=comecaes (liste 1 2 (6 2 40)))) 





T ;; => the structural equivalence is used also for any kind of arrays 
(let ((hashl (make-hash-table)) 
hash2 (make-hash-table))) 
setf (gethash 'key hashl) 4 
setf (gethash 'key hash2) 4 
print (equalp hashl hash2)) 
setf (gethash 'another-key hashl) 84) 

equalp hashl hash2) ) 

77 => after the first two insertions, hashl and hash2 have the same keys and values 
NIL ;; => after the third insertion, hashl and hash2 have different keys and values 


) 


2 
2) 





(progn (defstruct s) (equalp (make-s) (make-s))) 





T ;; => the two values are structurally equal 

(progn (defclass c () ()) (equalp (make-instance 'c) (make-instance 'c))) 

NIL ;; => two structurally equivalent class instances returns NIL, it's up to the user to 
28 define an equality method for classes 





Finally, rrez-Eouan Can be applied to structures built through consand checks if they are isomorphic, 
like zouaz but leaving to the user the choice of which function to use to compare the leafs, i.e. the 
non-cons (atom) encountered, that can be of any other data type (by default, the test used on 
atom is sot). For instance: 


ys) 


























(lee A AE) 

(22 qL a (AY a ayy) 
(tree-equal 11 12 :test #'eql)) 

NIL ;; => since (eql "A" "A") gives NIL 
CESE A Lg (Ng 3) ))) 

A o (RY > ayy) 
(tree-equal 11 12 :test #'equal) ) 








T ;; Since (equal "A" "A") gives T 


Comparison operators on numeric values 


Numeric values can compared with = and the other numeric comparison operators (/=, <, <=, >, >=) 
that ignore the difference in the physical representation of the different types of numbers, and 
perform the comparison of the corresponding mathematical values. For instance: 











(= 42 42) 

T ;; => both number have the sme numeric type and the same value 

(= 1 1.0 1d0) 

LAR => EuULiL elo Cr values represent the number 1, while for instance (eql 1 1d0) => NIL 
wee since it returns true only if the operands have the same numeric type 

(OO O10) 

T ;; => again, the value is the same, while (eql 0.0 -0.0) => NIL 








(= 3-0 (8,0 0,0)) 

[ ;; => a complex number with 0 imaginary part is equal to a real number 

(= 0.33333333 11184811/33554432) 

[ ;; => since a float number is passed to RATIONAL before comparing it to another number 
77 => and (RATIONAL 0.33333333) => 11184811/33554432 in 32-bit IEEE floats architectures 
(NOS 55858S5 55 07333533) 
[ ;; => since the result of RATIONAL on both numbers is equal in 32-bit IEEE floats 
architectures 

(= 0.33333333d0 0.33333334d0) 

NIL ;; => since the RATIONAL of the two numbers in double precision is different 
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From these examples, we can conclude that = is the operator that should normally be used to 
perform comparison between numeric values, unless we want to be strict on the fact that two 
numeric values are equal only if they have also the same numeric type, in which case zon should 
be used. 





Comparison operators on characters and strings 


Common Lisp has 12 type specific operators to compare two characters, 6 of them case sensitives 
and the others case insensitives. Their names have a simple pattern to make easy to remember 
their meaning: 


Case Sensitive | Case Insensitive 


CHAR= CHAR-EQUAL 

CHAR/= CHAR-NOT-EQUAL 
CHAR< CHAR-LESSP 

CHAR<= CHAR-NOT-GREATERP 
CHAR> CHAR-GREATERP 
CHAR>= CHAR-NOT-LESSP 


Two characters of the same case are in the same order as the corresponding codes obtained by 
cHAR-CODE, While for case insensitive comparisons the relative order between any two characters 
taken from the two ranges a..z, a..z is implementation dependent. Examples: 





char= #\a Hua) 





( 

T ;; => the operands are the same character 
(char= #\a HA) 

NIL ;; => case sensitiv quality 


(CHAR-EQUAL #\a #\A) 

I pp => Case inmsensiliciy quality 

(char> #\b #\a) 

T ;; => since in all encodings (CHAR-CODE #\b) is always greater than (CHAR-CODE #\a) 
(char-greaterp #\b \#A) 

T ;; => since for case insensitive the ordering is such that A=a, B=b, and so on, 




















PE and furthermore either 9<A or Z<0. 
(char> #\b HA) 
2? 77 => the result is implementation dependent 


For strings the specific operators are srrinc=, STRING-EQUAL, etc. with the word STRING instead of 
CHAR. Two strings are equal if they have the same number of characters and the correspending 
characters are equal according to cuar= Or char-E0UaL if the test is case sensitive or not. 








The ordering between strings is tje lexicographic order on the characters of the two strings. When 
an ordering comparison succeeds, the result is not r, but the index of the first character in which 
the two strings differ (which is equivalent to true, since every non-NIL object is a “generalized 
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boolean” in Common Lisp). 


An important thing is that a// the comparison operators on string accept four keywords parameters: 
startl, endl, start2, end2, that can be used to restrict the comparison to only a contiguous run of 
characters inside one or both strings. The start index if omitted is 0, the end index is omitted is 
equal to the length of the string, and the comparison in performed on the substring starting at 
character with index : start and terminating with the character with index :ena - 1 included. 


Finally, note that a string, even with a single character, cannot be compared to a character. 


Examples: 


Sicrwame= "Ego Wseee@"?)) 





( 
T ;; => both strings have the same lenght and the characters are 'CHAR=" in order 
(Siersinicg O O EE OCN), 





NIL ;; => case sensitive comparison 
(Stata e quelo OE O ON) 





[ ;; => case insensitive comparison 
(Gteing BO Ol O OO e CS Saa ES») 





[ ;; => the comparison is perform on substrings 

(strings “rogar? OO cites) 

3 ;; => the first string is lexicographically less than the second one and 
pE the first character different in the two string has index 3 
(strings Vioo EE Ol ata) 





3 ;; => the first string is a prefix of the second and the result is its length 


As a special case, the string comparison operators can also be applied to symbols, and the 
comparison is made on the symso1-xame of the symbol. For instance: 





(string= 'a "A") 
[ ;; since (SYMBOL-NAME 'a) is "A" 
Gering < gua cl a) 








T ;; since the the symbol names are "a" and "A" respectively 








As final note, zo. on characters is equivalent to cuar=; zouar On strings is equivalent to sTRING= 
while zovarr on strings is equivalent to STRING-EQUAL. 


J 








Overwiew 


In Common Lisp there are many different predicates for comparing values. They can be classified 
in the following categories: 


1. Generic equality operators: EQ, EQL, EQUAL, EQUALP. They can be used for values of any 
type and return always a boolean value T or NIL. 

2. Type specific equality operators: = and = for numbers, CHAR= CHAR= CHAR-EQUAL 
CHAR-NOT-EQUAL for characters, STRING= STRING= STRING-EQUAL STRING-NOT- 
EQUAL for strings, TREE-EQUAL for conses. 

3. Comparison operators for numeric values: <, <=, >, >=. They can be applied to any type of 
number and compare the mathematical value of the number, independently from the actual 
type. 

4. Comparison operators for characters, like CHAR<, CHAR-LESSP, etc., that compare 
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characters either in a case sensitive way or in a case insensitive way, according to an 
implementation depending order that preserves the natural alphabetical ordering. 

5. Comparison operators for strings, like STRING<, STRING-LESSP, etc., that compare strings 
lexicographically, either in a case sensitive way or in a case insensitive way, by using the 
character comparison operators. 


Read Equality and other comparison predicates online: https://riptutorial.com/common- 
lisp/topic/10064/equality-and-other-comparison-predicates 
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Chapter 13: format 


Parameters 


Lambda-List | (format DESTINATION CONTROL-STRING &REST FORMAT-ARGUMENTS) 


the thing to write to. This can be an output stream, + (shorthand for +standara- 


DESTINATION ñ x . 
output*), Or ni1 (which creates a string to write to) 





the template string. It might be a primitive string, or it might contain tilde- 





on prefixed command directives that specify, and somehow transform additional 
arguments. 
FORMAT- a ecchi | t red PAREI 
AETR potential additional arguments required by the given coNTROL-STRING. 
Remarks 


The CLHS documentation for rormar directives can be found in Section 22.3. With SLIME, you can 
type c-c c-a ~ to look up the CLHS documentation for a specific format directive. 


Examples 


Basic Usage and Simple Directives 


The first two arguments to format are an output stream and a control string. Basic use does not 
require additional arguments. Passing + as the stream writes to *standard-output*. 


> (format t "Basic Message") 
Basic Message 
makil 


That expression will write Basic Message to standard output, and return ni1. 
Passing ni1 as the stream creates a new string, and returns it. 


> (format nil "Basic Message") 
"Basic Message" 


Most control string directives require additional arguments. The -a directive ("aesthetic") will print 
any argument as though by the princ procedure. This prints the form without any escape 
characters (keywords are printed without the leading colon, strings without their surrounding 
quotes and so forth). 


> (from mall WA reses ad 42) 
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"A Test: 42" 

> (Gtomuee MLL MA pS SE =a ~a =a ~a” L (liat 2 3) Wikowie Siye ¢ S55) 
WiMiolicijolless i (2 3) fouz five Suc! 

> (format nil "A Test: ~a" :test) 

ARTES tE TES TI 

> (format nil "A Test: -a" "Example") 

"A Test: Example" 








-a Optionally right or left-pads input based on additional inputs. 

















> (format nil "A Test: -10a" "Example") 
"A Test: Example ai 
> (format nil "A Test: ~10@a" "Example") 
A Test: Example" 








The ~s directive is like ~a, but it prints escape characters. 























zir ornat mil Wa mess 5% 42) 

"A Test: 42" 

>= (ronner mil Ms SE SE SS i (lket 2 o) O SS) 
MMipiilicsljolless L (2 3) Aito: Edie ¿0 

>) (formate nay WA test: SE SST) 

HA esto SHko Iih 

> (format nil "A Test: -s" "Example") 

va test: A Bcamp le uy 


Iterating over a list 
One can iterate over a list using ~; and ~, directives. 


CET USER (leer je Wetec, wets VIL 2 si SNA) 
Lo 2p Se Ly Be 





~^ can be used to escape if there are no more elements left. 


CET SER (EE e A (AS O) 
Lo Gp Sp Uy Y 





A numeric argument can be given to -: to limit how many iterations can be done: 


SEU SE (EE ES 4 5J) 
Ll. Bp Se 





~e{ will iterate over remaining arguments, instead of a list: 


SEUS HEM (PEO A EA E O OS LO) 
mo0s 1, 2, 3 4 3 





Sublists can be iterated over by using -: (: 


CTS SER (LE © Vest (se, sa) jes’ Y CC 2) (3 4) S 6))) 
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Conditional expressions 


Conditional expressions can be done with ~; and -;. The clauses of the expression are separated 
using -;. 


By default, - ¡ takes an integer from the argument list, and picks the corresponding clause. The 
clauses start at zero. 


(format t "~@{~[First clause~;Second clause~;Third clause~;Fourth clause~]~%~}" 


Ot 2 3) 
First clause 
Second clause 
Third clause 
Fourth clause 


The last clause can be separated with ~:; instead to make it the else-clause. 


(format t "~@{~[First clause~;Second clause~;Third clause~:;Too high!~]~%~}" 


, 


r 


Ol 2 Ss & S) 
First clause 
Second clause 
Third clause 
Too high! 
Too high! 





Too high! 


If the conditional expression starts with ~: p, it will expect a generalized boolean instead of an 
integer. lt can only have two clauses; the first one is printed if the boolean was nit, and the 
second clause if it was truthy. 


(format t "~@{~: [False!~;True! ~]~%~}" 


, 


E mil O vroot «nhy 
True! 
False! 
True! 





True! 
False! 


If the conditional expression starts with ~er, there should only be one clause, which is printed if the 
input, a generalized boolean, was truthy. The boolean will not be consumed if it is truthy. 


(format t "~@{~@[~s rE 


, 
, 


, 


E al a Moo 11) 
Tis Esmuelayl 


5 10 de tesxuclayyl 


Moo ads tesuclal 


Read format online: https://riptutorial.com/common-lisp/topic/687/format 
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Chapter 14: Functions 


Remarks 





Anonymous functions can be created using 12uena. Local functions can be defined using 122215 Or 


rier. Their parameters are defined the same was as in global named functions. 





Examples 
Required Parameters 


(defun foobar (x y) 
(format t "X: -s-Q 
Y: ~s~%" 


x y)) 


(oO obans ORO) 
pos IO 
p ME 20 
¡=> NIL 


Optional Parameters 


Optional parameters can be specified after required parameters, by using sorrrowa keyword. 
There may be multiple optional parameters after it. 


(defun foobar (x y &optional z) 
(format t "X (~s) and Y (~s) are required.~@ 
m (=s) dis Goriomal, =s% 
x y Z)) 


(eccer 1O 20% 

; X (10) and Y (20) are required. 
p 4 NID is eyprlomall. 

¿=> NIL 

(Foobar IO 20 30) 

; X (10) and Y (20) are required. 
5 #4 (30) is oprional, 

¿=> NIL 


Default alue 


A default value can be given for optional parameters by specifying the parameter with a list; the 
second value is the default. The default value form will only be evaluated if the argument was 
given, so it can be used for side-effects, such as signalling an error. 


(defun foobar (x y &o0ptional (z "Default") ) 
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(format t "X (~s) and Y (~s) are required.~@ 
Z (~s) Us optional.=3" 
x Y 2)) 


(foobar 10 20) 

; X (10) and Y (20) are required. 
; 4 ("Default") is optional. 

¡=> NIL 

(Eooba LO 08S/0») 

; X (10) and Y (20) are required. 
¿2 (30) as) epticaal.. 

¡=> NIL 


Check if optional argument was given 


A third member can be added to the list after the default value; a variable name that is true if the 
argument was given, or x11 if it wasn't given (and the default is used). 


(defun foobar (x y &o0ptional (z "Default" zp) ) 


(format t "X (~s) and Y (~s) are required.~@ 
Z (~s) is optional. It ~:[wasn't~;was~] given.~%" 
x y z zp)) 


(foobar 10 20) 

; X (10) and Y (20) are required. 

5 4 (Mbestealen) 13 epicdomall. me masa giyen, 
¿=> NIL 

(foobar 10 20 30) 

; X (10) and Y (20) are required. 

A ES O) is MO pon As Givan, 

¿=> NIL 


Function without Parameters 


Global named functions are defined with perun. 





(defun foobar () 
"Optional documentation string. Can contain line breaks. 


ust be at the beginning of the function body. Some will format the 
docstring so that lines are indented to match the first line, although 
the built-in DESCRIBE-function will print it badly indented that way. 

















Ensure no line starts with an opening parenthesis by escaping them 
\(like this), otherwise your editor may have problems identifying 








toplevel forms." 
(format t "No parameters.-%")) 


(foobar) 
; No parameters. 
¿=> NIL 


(describe #'foobar) ; The output is implementation dependant. 


; #<FUNCTION FOOBAR> 
; [compiled function] 
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; Lambda-list: () 
; Derived type: (FUNCTION NIL (VALUES NULL &OPTIONAL) ) 


; Documentation: 








$ Optional documentation string. Can contain line breaks. 


8 Must be at the beginning of the function body. Some will format the 





$ docstring so that lines are indented to match the first line, although 
A the built-in DESCRIBE-function will print it badly indented that way. 
; Source file: /tmp/fileInaZ1P 

¡=> No values 














The function body may contain any number of forms. The values from the last form will be 
returned from the function. 


Rest Parameter 


A single rest-parameter can be given with the keyword «crest after the required arguments. If such 
a parameter exists, the function can take a number of arguments, which will be grouped into a list 
in the rest-parameter. Note that the variable ca1.1-arcuments-11m1T determines the maximum 
number of arguments which can be used in a function call, thus the number of arguments is limited 
to an implementation specific value of minimum 50 or more arguments. 











(defun foobar (x y &rest rest) 


(format t "X (~s) and Y (~s) are required.~@ 
The function was also given following arguments: ~s~%" 
x y rest)) 


(oo bar 1O 20) 

; X (10) and Y (20) are required. 

; The function was also given following arguments: NIL 

¿=> NIL 

(foobar 10 20 30 40 50 60 70 80) 

; X (10) and Y (20) are required. 

; The function was also given following arguments: (30 40 50 60 70 80) 
¿=> NIL 


Rest and Keyword Parameters together 


The rest-parameter may be before keyword parameters. In that case it will contain the property list 
given by the user. The keyword values will still be bound to the corresponding keyword parameter. 


(defun foobar (x y &rest rest &key (z 10 zp)) 


(format t "X (~s) and Y (~s) are required.~@ 
Z (~s) is a keyword argument. It ~:[wasn't~;was~] given.~@ 
The function was also given following arguments: ~s~%" 


x We zp rest) 


(foobar 10 20) 

; X (10) and Y (20) are required. 

; Z (10) is a keyword argument. It wasn't given. 

; The function was also given following arguments: NIL 
¡=> NIL 
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(foobar 10) 20 <2) 30) 

; X (10) and Y (20) are required. 

; Z (30) is a keyword argument. It was given. 

; The function was also given following arguments: (:Z 30) 
¡=> NIL 





Keyword saLLow-oTHER-KeEYS Can be added at the end of the lambda-list to allow the user to give 
keyword arguments not defined as parameters. They will go in the rest-list. 














(defun foobar (x y &rest rest &key (z 10 zp) &allow-other-keys) 


(format t "X (~s) and Y (~s) are required.~@ 
Z (~s) is a keyword argument. It ~:[wasn't~;was~] given.~@ 
The function was also given following arguments: ~s~%" 


X Y Z zp rest) ) 


(EOI 20) 3x4 30 gre; 40) 

; X (10) and Y (20) are required. 

; Z (30) is a keyword argument. It was given. 

; The function was also given following arguments: (:Z 30 :Q 40) 
¡=> NIL 


Auxiliary Variables 


The saux keyword can be used to define local variables for the function. They are not parameters; 
the user cannot supply them. 


«aux Variables are seldomly used. You can always use tet instead, or some other way of defining 
local variables in the function body. 





«aux Variables have the advantages that local variables of the whole function body move to the top 
and it makes one indentation level (for example introduced by a LET) unnecessary. 


(defun foobar (x y &aux (z (+ x y))) 
(format t "X (~d) and Y (~d) are required.~@ 
Toesig Stim als al, 
= E) ) 
(oo bar e020) 
; X (10) and Y (20) are required. 


CIS US S0, 
¡=> NIL 


One typical usage may be resolving "designator" parameters. Again, you need not do it this way; 
using 1et is just as idiomatic. 


(defun foo (a b aux (as (string a))) 
"Combines A and B in a funny way. A is a string designator, B a string." 
(concatenate 'string as " is funnier than " b)) 


RETURN-FROM, exit from a block or a function 


Functions always establish a block around the body. This block has the same name as the 
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function name. This means you can use rerurn-rrom With this block name to return from the 
function and return values. 


You should avoid returning early whenever possible. 


(defun foobar (x y) 
(when (oddp x) 
(format t "X (~d) is odd. Returning immediately.~%" x) 
(return-from foobar "return value") ) 
(format t "X: ~s~@ 
We egal 
x y)) 


(Goobar 0210) 


A oe 10) 
pS 20) 
¡=> NIL 


(foobar 9 20) 
; X (9) is odd. Returning immediately. 
¡=> "return value" 


Keyword Parameters 





Keyword parameters can be defined with the sxey keyword. They are always optional (see the 
Optional Parameters example for details of the definition). There may be multiple keyword 
parameters. 


(defun foobar (x y &key (z "Default" zp)) 


(format t "X (~s) and Y (~s) are required.~@ 
Z (~s) is a keyword argument. It ~:[wasn't~;was~] given.~%" 
x y Zz zp)) 


(foobar 10 20) 

AE OA O) re regui redi 

; Z ("Default") is a keyword argument. It wasn't given. 
¡=> NIL 

(oa 10 20 gx 30) 

poe (LO) ame Y (20) aze regu readh 

; Z (30) is a keyword argument. It was given. 

¿=> NIL 


Read Functions online: https://riptutorial.com/common-lisp/topic/2126/functions 
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Chapter 15: Functions as first class values 


Syntax 


e (function name) ; retrieves the function object of that name 
e name ; syntactic sugar for (function name) 
e (symbol-function symbol) ; returns the function bound to symbol 
(funcall function args...) ; call function with args 
e (apply function arglist) ; call function with arguments given in a list 
(apply function arg1 arg2 ... argn arglist) ; call function with arguments given by arg1, arg2, 
..., argn, and the rest in the list arglist 





Parameters 

(paramen ea 
name some (unevaluated) symbol which names a function 
symbol a symbol 
function a function which is to be called 
args... zero or more arguments (not a list of arguments) 
arglist a list containing arguments to be passed to a function 


arg1, arg2, ..., argn each is a single argument to be passed to a function 


Remarks 


When talking about Lisp-like languages there is a common distinction between what is known as a 
Lisp-1 and a Lisp-2. In a Lisp-1, symbols only have a value and if a symbol refers to a function 
then the value of that symbol will be that function. In a Lisp-2, symbols can have separate 
associated values and functions and so a special form is required to refer to the function stored in 
a symbol instead of the value. 


Common Lisp is basically a Lisp-2 however there are in fact more than 2 namespaces (things that 
symbols can refer to) -- symbols can refer to values, functions, types and tags, for example. 


Examples 


Defining anonymous functions 


Functions in Common Lisp are first class values. An anonymous function can be created by using 
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lambda. For example, here is a function of 3 arguments which we then call using funca11 








cisusiass> (lemicck (a lo e) (4 a ( Is E))) 

#<FUNCTION (LAMBDA (A B C)) (10034F484B)> 

CAUSE O So ON lam (COS (r a © Je CDD) 
“HOOK 














CU=USER> (funcall *foo* 1 2 3) 
7 


Anonymous functions can also be used directly. Common Lisp provides a syntax for it. 


(Miémoda (alo e) (E 2 (5 lo E))) ; the lambda expression as the first 
; element in a form 
i 2 3) ; followed by the arguments 


Anonymous functions can also be stored as global functions: 


(let ((a-function (lambda (a b c) (+ a (* b c))))) ¿ our anonymous function 
(setf (symbol-function 'some-function) a-function)) 7 Storing Le 
(some-function 1 2 3) ; Calling it with the name 


Quoted lambda expressions are not functions 


Note that quoted lambda expressions are not functions in Common Lisp. This does not work: 


(funcall '(lambda (x) x) 
42) 


To convert a quoted lambda expression to a function use coerce, eval OF funcall: 





CL-USER > (coerce "(lambda (x) x) 'function) 
<anonymous interpreted function 4060000A7C> 


CL-USER > (eval '(lambda (x) x)) 
<anonymous interpreted function 4060000B9C> 

















CL-USER > (compile nil '(lambda (x) x)) 
<Function 17 4060000CCC> 











Referring to Existing Functions 


Any symbol in Common Lisp has a slot for a variable to be bound and a separate slot for a 
function to be bound. 


Note that the naming in this example is only for illustration. Global variables should not be named 
foo, but *fo0*. The latter notation is a convention to make it clear that the variable is a special 
variable using dynamic binding. 


CL-USER> (boundp 'foo) ;is FOO defined as a variable? 
NIL 
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USER> (defvar foo 7) 





O 
O 





l 
C 
ide) 
kai 
py 
V 


(boundp 'foo) 


JUSER> foo 








USER- (symbol-value 'foo) 





(fboundp 'foo) ¡is FOO defined as a function? 











Ot Qu Oo 02000 
E n E 
c 
un 
al 
W 
Vv 











EG 
SEEM (SURE Oe (A (EA E) 0) 
00 
-USER> (fboundp 'foo) 
USER> foo 
-USER> (symbol-function 'foo) 
<FUNCTION FOO> 
CL-USER> (function foo) 
<FUNCTION FOO> 
SER> (equalp (quote #'foo) (quote (function foo))) 





CL-USER> (eq (symbol-function 'foo) #'foo) 











i-USER> (foo 4 3) 





@ ts © 
al 


USER= (ttuncall too 4 3) 
ain Eros Y ads mor E ie wlinyclesloim 
i-USER> (funcall #'foo 4 3) 





Q 
10) 
ct 





ol 
| 
£ 
n 


ER> (defvar bar #'foo) 





PoE 
py] 


—USER> bar 
NCTION FOO> 
=USER>= (funcall bar 4 3) 








on 





—USER> #'+ 
<FUNCTION +> 
FUSS EU e IA IZ 3) 




















n G w O V A ae G josh (Or (Sr Wr SS 
ea 
C 


Higher order functions 


Common Lisp contains many higher order functions which are passed functions for arguments and 


call them. Perhaps the most fundamental are funcaii and appiy: 


SUSER- MES i 2 3) 



































(CEU 

(il 2 3) 

CE-USER> (tuncall “ise 1 2 3) 

(il 2 3) 

CL=-USER> (funcall ise 123 4 5) 
(l 2 3 4 8) 

CESUSER (pps 7% (al 2 3))}) 
(il 2 3) 

CAUSER (apply IES a 2 Y (4 &))) 
(l 2 3 4 8) 

CESUSER (eyes, qevar ES 2 33) )) 
6 

e 











PUSER (defun my-funcall (function &rest args) 





https://riptutorial.com/ 


52 


(apply function args)) 
MY-FUNCALL 
CASUSERN (my uns IES il 2 3) 
(Gees) 





There are many other higher order-function which, for example, apply a function many times to 
elements of a list. 





























CLSUSE R= A (map S/N OSA) 

G 1/2 1/3 1/2) 

CLAaUSINRS (meio Yweeie Guar SO A SES 2 10))) 
wie @ @ © IL) 

CL-USER> (reduce #'+ '(1 2 3 4 5)) 

15 

CL-USER> (remove-if #'evenp '(1 2 3 4 5)) 

( 


Summing a list 
The reduce function can be used to sum the elements in a list. 


(meduce A SA) 
=> 110) 


By default, reduce performs a /eft-associative reduction, meaning that the sum 10 is computed as 


The first two elements are summed first, and then that result (3) is added to the next element (3) to 
produce 6, which is in turn added to 4, to produce the final result. 


This is safer than using apply (e.g., in (apply '+ '(1 2 3 4)) because the length of the argument list 
that can be passed to apply is limited (see call-arguments-limit), and reduce will work with 
functions that only take two arguments. 


By specifying the from-end keyword argument, reduce will process the list in the other direction, 
which means that the sum is computed in the reverse order. That is 


(reduce *+ (1 2 3 A) :from-end t) 
;;=> 10 


is computing 
(ae aL (Gp 2 (CES AI 


Implementing reverse and revappend 


Common Lisp already has a reverse function, but if it didn't, then it could be implemented easily 
using reduce. Given a list like 
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MARES COS leons 2 ors S (00) 
the reversed list is 
(cons 3 (cons 2 (cons 1 "()))) === (3 2 1) 


That may not be an obvious use of reduce, but if we have a "reversed cons" function, say xcons, 
such that 


(xcons 1 2) === (2 . 1) 
Then 
(scons (scons (scons () 21) 2) =) 


which is a reduction. 


(reduce (lambda (x y) 
(Cons) y =))) 
v(l 2S 4) 
:initial-value '()) 
p= (4 a 2 i) 


Common Lisp has another useful function, revappend, which is a combination of reverse and 
append. Conceptually, it reverses a list and appends it to some tail: 


(revappend '(3 2 1) '(4 5 6)) 
his (lL 2s 4 & OS) 


This can also be implemented with reduce. It fact, it's the same as the implementation of reverse 
above, except that the initial-value would need to be (4 5 6) instead of the empty list. 


(reduce (lambda (x y) 
(cons y =))) 
e 2 
:initial-value '(4 5 6)) 
po (il 2 Sa ds Gy) 


Closures 


Functions remember the lexical scope they where defined in. Because of this, we can enclose a 
lambda in a let to define closures. 


(defvar *counter* (let ((count 0)) 

(Tambaa 0) (inek count) hi 
(funcall *eounter*) 33 == 1 
(funcall *counter*l 3; = 2 
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In the example above, the counter variable is only accessible to the anonymous function. This is 
more clearly seen in the following example 


(defvar *counter-1* (make-counter)) 
(defvar *counter-2* (make-counter)) 


cunca Lil *couimececr=i:) pp => 
punea «commesr=1) pp => 
uneca Lil counter 22i => 


( 
( 
( 
( 


WORPNE 


punea counter 1) AA => 


Defining functions that take functions and return functions 


A simple example: 





CL-USER> (defun make-apply-twice (fun) 
"return a new function that applies twice the function’ fun' to its argument" 
(lambda (x) 
(funcall fun (funcall fun <))1) 
MAKE-APPLY-TWICE 
CL-USER> (funcall (make-apply-twice #'1+) 3) 




















CL-USER> (let ((pow4 (make-apply-twice (lambda (x) (* x x))))) 
(funcall pow4 3)) 
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The classical example of function composition: (fo go M(X) = f(g (h (X): 





CL-USER> (defun compose (&rest funs) 
"return a new function obtained by the functional compositions of the parameters" 
(ie AS) 








$ "identity 
(let ((rest-funs (apply #'compose (rest funs)))) 
(lambda (x) (funcall (first funs) (funcall rest-funs x)))))) 
COMPOSE 
CL-USER> (defun square (x) (* x x)) 
SQUARE 
CL-USER> (funcall (compose #'square #'1+ #'square) 3) 











100 ;; => equivalent to (square (1+ (square 3))) 


Read Functions as first class values online: https://riptutorial.com/common- 
lisp/topic/1259/functions-as-first-class-values 
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Chapter 16: Grouping Forms 


Examples 


When is grouping needed? 


In some places in Common Lisp, a series of forms are evaluated in order. For instance, in the 
body of a defun or lambda, or the body of a dotimes. In those cases, writing multiple forms in 
order works as expected. In a few places, however, such as the then and else parts of an if 
expressions, only a single form is allowed. Of course, one may want to actually evaluate multiple 
expressions in those places. For those situations, some kind of implicit of explicit grouping form is 
needed. 


Progn 


The general purpose special operator progn is used for evaluating zero or more forms. The value 
of the last form is returned. For instance, in the following, (print 'hello) is evaluated (and its result 
is ignored), and then 42 is evaluated and its result (42) is returned: 


(progn 
(print 'hello) 
42) 

¿=> 42 


If there are no forms within the progn, then nil is returned: 


(progn) 
¿=> NIL 


In addition to grouping a series of forms, progn also has the important property that if the progn 
form is a top-level form, then all the forms within it are processed as top level forms. This can be 
important when writing macros that expand into multiple forms that should all be processed as top 
level forms. 


Progn is also valuable in that it returns a// the values of the last form. For instance, 


(progn 
(print 'hello) 
(values 1 2 3)) 
y= l, 2; 3 


In contrast, some grouping expressions only return the primary value of the result-producing form. 
Implicit Progns 


Some forms use implicit progns to describe their behavior. For instance, the when and unless 
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macros, which are essentially one-sided if forms, describe their behavior in terms of an implicit 
progn. This means that a form like 


(when (foo-p foo) 
forml 
form2) 


is evaluated and the condition (foo-p foo) is true, then the form? and form2 are grouped as 
though they were contained within a progn. The expansion of the when macro is essentially: 


(Gi (OOO 200) 
(progn 
forml 
form2) 
nil) 


Prog1 and Prog2 


Often times, it is helpful to evaluate multiple expressions and to return the result from the first or 
second form rather than the last. This is easy to accomplish using let and, for instance: 


(let ((forml-result forml)) 
form2 
form3 
Pb 
ll 
OK 
forml-result) 


Because this form is common in some applications, Common Lisp includes prog1 and prog2 that 
are like progn, but return the result of the first and second forms, respectively. For instance: 


(progl 
42 
(print 'hello) 
(print 'goodbye) ) 
jp => 42 


(prog2 

(print 'hello) 

42 

(print 'goodbye) ) 
pp => da 


An important distinction between prog1/prog2 and progn, however, is that progn returns al/ the 
values of the last form, whereas prog1 and prog2 only return the primary value of the first and 
second form. For instance: 


(progn 
(print 'hello) 
(values 1 2 3)) 
=> IS 
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(progl 
(values 1 2 3) 
(print 'hello)) 
ges 1 7 moe l 2, 3 


For multiple values with prog1 style evaluation, use multiple-value-prog1 instead. There is no 
similar multiple-value-prog2, but it is not difficult to implement if you need it. 


Block 


The special operator block allows grouping of several Lisp forms (like an implicit progn) and it also 
takes a name to name the block. When the forms within the block are evaluated, the special 
operator return-from can be used to leave the block. For instance: 


(block foo 
(print 'hello) ; evaluated 
(return-from foo) 
(print 'goodbye) ) ; not evaluated 
77=> NIL 


return-from can also be provided with a return value: 


(block foo 
(print 'hello) ; evaluated 
(return-from foo 42) 
(print 'goodbye) ) a not evaluated 
pp=> 42 


Named blocks are useful when a chunk of code has a meaningful name, or when blocks are 
nested. In some context, only the ability to return from a block early is important. In that case, you 
can use nil as the block name, and return. Return is just like return-from, except that the block 
name is always nil. 


Note: enclosed forms are not top-level forms. That's different from progn, where the enclosed 
forms of a top-level progn form are still considered top-/evel forms. 


Tagbody 


For lots of control in a group forms, the tagbody special operator can be very helpful. The forms 
inside a tagbody form are either go tags (which are just symbols or integers) or forms to execute. 
Within a tagbody, the go special operator is used to transfer execution to a new location. This 
type of programming can be considered fairly low-level, as it allows arbitrary execution paths. The 
following is a verbose example of what a for-loop might look like when implemented as a tagbody: 


(let (x) p oz (Gk = Op << Dp xr) ( pinte (ellop } 
(tagbody 
(setq x 0) 
prologue 
(unless, le x: 5) 
(go end)) 
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begin 

(Pein ea (Liar Snella i) 
epilogue 

CEEE) 

(go prologue) 
end) ) 


While tagbody and go are not commonly used, perhaps due to "GOTO considered harmful", but 
can be helpful when implementing complex control structures like state machines. Many iteration 
constructs also expand into an implicit tagbody. For instance, the body of a dotimes is specified 
as a series of tags and forms. 


Which form to use? 


When writing macros that expand into forms that might involve grouping, it is worthwhile spending 
some time considering what grouping construction to expand into. 


For definition style forms, for instance, a define-widget macro that will usually appear as a top- 
level form, and that several defuns, defstructs, etc., it usually makes sense to use a progn, so 
that child forms are processed as top-level forms. For iteration forms, an implicit tagbody is more 
common. 


For instance, the body of dotimes, dolist, and do each expand into an implicit tagbody. 


For forms that define a named "chunk" of code, an implicit block is often useful. For instance, 
while the body of a defun is inside an implicit progn, that implicit progn is within a block sharing 
the name of the function. That means that return-from can be used to exit from the function. Such 
a comp 


Read Grouping Forms online: https://riptutorial.com/common-lisp/topic/4892/grouping-forms 
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Chapter 17: Hash tables 


Examples 


Creating a hash table 
Hash tables are created by make-hash-table: 


(defvar *my-table* (make-hash-table)) 





The function may take keyword parameters to further specify the behavior of the resulting hash 
table: 


e test: Selects the function used to compare keys for equality. Maybe a designator for one of 
the functions eq, eql, equal Ol equalp. The default is eq. 

* size: A hint to the implementation about the space that may initially be required. 

* rehash-size: If an integer (>= 1), then when doing a rehash, the hash table will increase its 
capacity by the specified number. If otherwise an float (> 1.0), then the hash table will 
increase its capacity to the product of the renash-size and the previous capacity. 

* rehash-threshold: Specifies how full the hash table has to be in order to trigger a rehash. 


Iterating over the entries of a hash table with maphash 


(defun print-entry (key value) 
(format t "~A => ~A~%" key value) ) 


(maphash iprint entry *my-table*) ;; => NIL 


Using maphash allows to iterate over the entries of a hash table. The order of iteration is 
unspecified. The first argument is a function accepting two parameters: the key and the value of 
the current entry. 


maphash always returns nit. 
Iterating over the entries of a hash table with loop 


The loop macro supports iteration over the keys, the values, or the keys and values of a hash 
table. The following examples show possibilities, but the full loop syntax allows more 
combinations and variants. 


Over keys and values 


(let ((ht (make-hash-table) ) ) 
(setf (gethash 'a ht) 1 
(gethash 'b ht) 2) 
(loop for k being each hash-key of ht 
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using (hash-value v) 
collect (cons k v))) 
pase (UA. 1) (8 5 £)) 


(let ((ht (make-hash-table) ) ) 
(setf (gethash 'a ht) 1 
(gethash 'b ht) 2) 
(loop for v being each hash-value of ht 
using (hash-key k) 
collect (cons k AD) 
AO @ a 2)) 


Over keys 


(let ((ht (make-hash-table) ) ) 
(setf (gethash 'a ht) 1 
(gethash 'b ht) 2) 
(loop for k being each hash-key of ht 
collect k)) 
pp=> (a 18) 


Over values 


(let ((ht (make-hash-table))) 
(setf (gethash 'a ht) 1 
(gethash 'b ht) 2) 
(loop for v being each hash-value of ht 
collect v)) 
pie (L 2) 


Iterating over the entries of a hash table with a hash table iterator 


The keys and values of a hash table can be iterated over using the macro with-hash-table- 
iterator. This may be a bit more complex than maphash or loop, but it could be used to 
implement the iteration constructs used in those methods. with-hash-table-iterator takes a name 
and a hash table and binds the name within a body such that successive calls to the name 
produce multiple values: (i) a boolean indicating whether a value is present; (ii) the key of the 
entry; and (iii) the value of the entry. 


(let ((ht (make-hash-table) ) ) 
(setf (gethash 'a ht) 1 
(gethash 'b ht) 2) 
(with-hash-table-iterator (iterator ht) 
(print (multiple-value-list (iterator))) 





(print (multiple-value-list (iterator))) 
(print (multiple-value-list (iterator))))) 


pp (MD) 
T B 2) 
77 (NIL) 





`~ 
`~ 


Read Hash tables online: https://riptutorial.com/common-lisp/topic/4482/hash-tables 
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Chapter 18: Lexical vs special variables 


Examples 


Global special variables are special everywhere 
Thus these variables will use dynamic binding. 


(defparameter count 0) 
7; All uses of count will refer to this one 


(defun handle-number (number) 
(Macaco Uni) 
(format t "~&~d~%S" number) ) 
(dotimes (count 4) 
77 count is shadowed, but still special 
(handle-number count) ) 
(Gonmaewret calls se cl se Ounce) 


==> 


calilss 0 
Give special variables distinct names to avoid this problem: 


(defparameter *count* 0) 
(defun handle-number (number) 
(inet *count*,) 


(format t "~&~d~%S" number) ) 


(dotimes (count 4) 
(handle-number count) ) 


(format t ""¿Calls: ~d=s" *count*) 


Note 1: it is not possible to make a global variable non-special in a certain scope. There is no 
declaration to make a variable /exical. 


Note 2: it is possible to declare a variable special in a local context using the special declaration. If 
there is no global special declaration for that variable, the declaration is only locally and can be 
shadowed. 


(defun bar () 
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(declare (special a)) 
a) 


(defun foo () 
(let ((a 42)) 


(declare (special a)) 


(List (ose) 
(et (la 0)) 
(bar))))) 
> (FOG) 
(42 42) 


, 


t 


T 


value of A is looked up from the dynamic binding 


<- this variable A is special and 


dynamically bound 


<- this variable A is lexical 


Read Lexical vs special variables online: https://riptutorial.com/common-lisp/topic/3362/lexical-vs- 


special-variables 
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Chapter 19: LOOP, a Common Lisp macro for 
iteration 


Examples 
Bounded Loops 


We can repeat an action some number of times using repeat. 


CL-USER> (loop repeat 10 do (format t "Hello!~%")) 
Hello! 





Lio! 


Mot 
Hello! 
llo! 
llo! 


Lio! 


Mol 
llo! 





I 
O D DA DD DDD 


Likes! 
JEM; 
CL-USER> (loop repeat 10 collect (random 50) ) 
(28 46 44 31 5 33 43 35 37 4) 














Looping over Sequences 


(loop for i in '(one two three four five six) 
do (print i)) 
(loop for i in '(one two three four five six) by #'cddr 

















do (print i)) ;prints ONE THREE FIVE 





(loop for 1 on (a lo e e e E q) 
do (foriae (lencia 1))) ¿ezintes 7654321 
(logs faz a on "(a lo e 6 e E) iow speckle 
))) 


)) ¿prints 7531 
a o €) 


iL) )} pistedines la io @) Ca ©) (e) 


( 
( 
( 

do (print (length i 
(loop for a om Y 
al 


do (forlmte 
(loos tor 1 across (Ll 2 3 4 5 0) 


do (forlae 4)) p priaes 123436 
(Hoop for i across “Ego 





do (orinc 1) p prints Ge 0 0 





(loop for element across "foo" 
for i from 0 





Glo (Format E "esa mae i element) y prints 0 ni oyal © 


Here is a summary of the keywords 





Sequence type | Variable type 


in list element of list 
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Sequence type | Variable type 


on list some car of list 


across vector element of vector 


Looping over Hash Tables 


(defvar *ht* (make-hash-table)) 

(loop for (sym num) on 
"(one 1 two 2 three 3 four 4 five 5 six 6 seven 7 eight 8 nine 9 ten 10) 
Dye da 

do (setf (gethash sym *ht*) num)) 


(loop for k being each hash-key of *ht* 
do (print k)) ; iterate over the keys 








(loop for k being the hash-keys in *ht* using (hash-value v) 
do (format t "-a=>-a-%" k v)) 





(loop for v being the hash-value in *ht* 
do (print v)) 





(loop for v being each hash-values of *ht* using (hash-key k) 





do (format t "~a=>~a~%" k v)) 


Simple LOOP form 
Simple LOOP form without special keywords: 


los» Edie. o.) 


To break out of the loop we can use (return <return value>) ` 


Some examples: 


(loop Mm (Senmae t Hello 0108) ; prints "Hello" forever 
(loop (print (eval (read)))) ; your very own REPL 





(loop (let ((r (read) ) ) 
(typecase r 
(number (return (print (* r r)))) 
(otherwise (format t "Not a number!~%"))))) 


Looping over Packages 


(loop for s being the symbols in 'cl 
do (rime s) ip) 





(loop for s being the present-symbols in :cl 

do (print s)) 

(loop for s being th xternal-symbols in (find-package "COMMON LISP") 
do (print s)) 

(loop for s being each external-symbols of "COMMON LISP" 

do (print s)) 














(loop for s being each external-symbol in pack ¡pack is a variable containing a package 





do (print s)) 
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Arithmetic Loops 











O ESAS 


Or a S ASS 7 


e J 1 


e J 1O 


MORAS G A 2 il 


lo 9376B4032 10 


prines L ti 2i sil 4 Si ol SO 


fp priimtas 100 90 0 70 60 50 40 30 20 10 © 


i+ (random 3)) 


; note that (random 3) is evaluated only once 


(+ step 1) 


; equivalent to the above 


oie 3 Excom 1 loy 11 
(omer © "e. 26l —SeleG" a JI) ¿PELS 


do 


(loop oz 1 rrom © to 10 
Glo (orime DO ins 
(loop for i from 0 below 10 
AA A ins 
(loop for i from 10 above 0 
Glo (orime ins 
(hows tor 1 mom 10 te 0 
Glo (omzilme DO $ prines motel] 
(loop for i from 10 downto 0 
cdo (orime 1)) $ joriaies 
(loop for i downfrom 10 to 0 
do (print i)) ; same as above 
(loop Eos a from L to LOO by 10 
Glo (oie LH $ 
(Leop tor L from 100 cloaca © by 10 
do (orime al) )) 
(loop tor 1 from L to 10 by ( 
do (orale aL) )) 
(let ((step (random 3))) 
(loss toz aL irom I to 10 lay 
Glo) (arami a1) I) 
(loop Eos i irom i to 10 


Destructuring in FOR statements 


We can destructure lists of compound objects 


ER> 





5) 


ER> 





N 
Hs 





US) 


6) 
ER> 








E 
( 
CT US 
( 
e 
( 


(hacia Eos 


(loop for 


(Loge Eos 


2 a te Li) 


la. 


la. 


la 


DEC) 


We can also destructure a list itself 














la. 


(a . 


CL-USER> (loop for 

G 2 545 6 

CL-USER> (loop for 

Ma 3 42450 (845 6) 


b) 


b) 


on 


on 


u(l S 4 ® &) 


IS 4 ® &) 


(4 5 6) (5 6) (6) NIL) 


L LIA 22\nosol@O LIO 


aM (5 . 6)) collect al 


a 4) (Ss. 6)) colilser 19) 


SY) (7 & 9) (O i 12)) 


collect a 


collect b 


This is useful when we want to iterate through only certain elements 


ER> 








5) 
ER> 








== ©) 
me i ds 
w 


(Hocpr kor 


(ocr sor 


(e a 


(er a 


b) 


b) 


Using w11 to ignore a term: 
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on 


on 


(1334 5 G) 


(1233456) 


by #'cddr collect a) 


by #'cdddr collect a) 


collect b) 


(loos itor (CO am V((l 25 3) (45 6) (7 8 
Colleee (list a bh) s= = (a 3) (4 6) (7 9)) 

(Loss tor (a lo) da YC (i 2) (3 4) (5 G)) ¿(a lo) == 
collect Gr a bo) => (5 + 11) 


; iterating over a window in a list 
(EoopRESM (PESADOS E) om V(l 235 45 3 2 it 2 Ss 4) 


ojo atn Erom L 





while (and x post) ; checks that we have thr 
1f (and (<= post x) (<= pre x)) collect (list 
if (and (>= post x) (>= pre x)) collect (list 


; The above collects local minima/maxima 


LOOP as an Expression 


lements of the list 
¿max x nth) 
giman $3 ea 


Unlike the loops in nearly every other programming language in use today, the 100» in Common 


Lisp can be used as an expression: 


Glee (doubled (Moca mor es Heron 1 ES 0 
collecte MERLO) 
doubled) ;; ==> (2 4 6 8 10 12 14 16 18 20) 


(oop eEOn sae con OA) ES II) 


MAXIMIZE Causes the oor to return the largest value that was evaluated. miximzz 





MAXIMIZE. 


(loop repeat 100 
(random 1000) 
maximize x) 


for x = 





= is the opposite of 


count tells you how many times an expression evaluated to non-x11 during the loop: 


(loop repeat 100 
(random 1000) 
(evenp x)) 


for x = 
count 


Loop also has equivalents of the some, every, and notany functions: 


(loop for ch across "foobar" 
thereis (eq ch #\a)) 


(loos tor x am "(a lo © Cl © i iL) 





always (symbolp x) ) 
(l@ojs oie x aim ' (il S & 7) 
never (evenp x) ) 


...except they're not limited to iterating over sequences: 


(loop for value = (read *standard-input* nil :eof) 
until (eq value :eof) 
never (stringp value) ) 


https://riptutorial.com/ 


67 


Loop value-generating verbs can also be written with an -ing suffix: 


(loop repeat 100 
for x = (random 1000) 
minimizing x) 


It is also possible to capture the value generated by these verbs into variables (which are created 
implicitly by the Loop macro), so you can generate more than one value at a time: 


(loop repeat 100 
for x= (random 1000) 
maximizing x into biggest 
minimizing x into smallest 
summing x into total 
collecting x into xs 
finally (return (values biggest smallest total xs))) 


You can have more than one collect, count, etc. clause that collects into the same output value. 
They will be executed in sequence. 


The following converts an association list (which you can use with assoc) into a property list (which 
you can use with get£): 


(loop for (key . value) in assoc-list 
collect key 
collect value) 


Although this is better style: 


(loop for (key . value) in assoc-list 
append (list key value)) 


Conditionally executing LOOP clauses 
Loop has its own ir statement that can control how the clauses are executed: 


(loop repeat 1000 
for x = (random 100) 
1f (evenp x) 
collect x into evens 
else 
collect x into odds 
finally (return (values evens odds))) 


Combining multiple clauses in an IF body requires special syntax: 


(loop repeat 1000 
for x = (random 100) 
if (evenp x) 
collect x into evens 
and do (format t "~a is even!~%" x) 
else 
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comes toro das 
and count t into n-odds 
finally (return (values evens odds n-odds))) 


Parallel Iteration 


Multiple ror clauses are allowed in a zoor. The loop finishes when the first of these clauses 
finishes: 


(logs toi a am Yq 23 4 5) 


ir@ie io aim Yla o ©) 
collect (liste a 19) )) 
Ba lates roS (C æ) o (5 ©) 





Other clauses that determine if the loop should continue can be combined: 


(Los» oi a da "(1 2 3A 5 € T) 
while (< a 4) 
collect a) 

3; Evaluates to: (1 2 3) 





(leo for a da "(123456 7) 
while (< a 4) 
repeat 1 
collect a) 





7; Evaluates to: (1) 
Determine which list is longer, cutting off iteration as soon as the answer is known: 


(Ceta longeso (lisc IES 52») 
los» for aciel on list=i 
tos lez om Jiisie=2 
de (Coni Seka eeuen ¿mall 
else if (null cdr2) return t 
caca (rercwvizm imal JL) )) 


Numbering the elements of a list: 


(loop tor trem tn “(a o e ol e E C) 
COT x eom il 
collect (cons x item)) 
AA Returns (U1 , ei) (2 , Io) (8 « ©) (4 . G) (© «. &) ( 2. ) (7 a S&S) 


Ensure that all the numbers in a list are even, but only for the first 100 items: 


(assert 
(loop for number in list 
repeat 100 
always (evenp number) )) 


Nested Iteration 
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The special Loop nameD foo syntax allows you to create a loop that you can exit early from. The exit 
is performed using return-from, and can be used from within nested loops. 


The following uses a nested loop to look for a complex number in a 2D array: 


(loop named top 
for x from 0 below (array-dimension *array* 1) 
do (loop for y from 0 below (array-dimension *array* 0)) 
for n = (aref *array* y x) 
when (complexp n) 
do (return-from top (values n x y)))) 


RETURN clause versus RETURN form. 


Within a Loop, you can use the Common Lisp (return) form in any expression, which will cause the 
Loop form to immediately evaluate to the value given to return. 





Loop also has a return Clause which works almost identically, the only difference being that you 
don't surround it with parentheses. The clause is used within toor's DSL, while the form is used 
within expressions. 


(Toop Bor x ía list 
do (if (listp x) ;; Non-barewords after DO are expressions 
(return :x-has-a-list))) 





;; Here, both the IF and the RETURN are clauses 
(ikeyoys: itore S< atin dlatsie 
ie SES) e as asi) 


7; Evaluate the RETURN expression and assign it to X... 

77 except RETURN jumps out of the loop before the assignment 

7; happens. 

(loop for x = (return :nothing-else-happens) 
do (print :this-doesnt-print)) 











The thing after sinai1y must be an expression, so the (return) form must be used and not the 
return Clause: 


(lace sor m tom L ta OG 
when (evenp n) collect n into evens 
else collect n into odds 
finally return (values evens odds)) ;; ERROR! 


(loss ei: im semen L ica 100 
when (evenp n) collect n into evens 
else collect n into odds 
finally (return (values evens odds))) ;; Correct usage. 


Looping over a window of a list 
Some examples for a window of size 3: 


7; Naive attempt: 
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(loos ior (first seconel maite) om “(Ll 2 3 4 5) 
do (print (* first second third))) 
pp DElaes 6 24 $60 tasa Brerozs om ( A 5 NEL) 





7; We will try again and put our attempt into a function 
(defun loop-3-windowl (function list) 
(loop zos (first secune. ales) om liste 

while (and second third) 

do (funcall function first second third))) 
(loop-3-windowl (lambda (a b c) (print (* ab c))) 
77 prints 6 24 60 and returns NIL 
Moso=3=mlbacieral (Ulemiosa (alo e) (felme (ise 2 lo 2))) “(alo e e mil mil e 1)) 
fp Drlaes la lo ©) (lo e el) tasca recoins Ida 


(las 4 S) 


7; A second attempt 
(defun loop-3-window2 (function list) 
(Hoop Hor $ em Liste 
while (nthcdr 2 x) ¿checks if there are at least 3 elements 





for (first second third) = x 

de (Func ietinciciom Sirsi secomel Taireh y) 
(loop 3min (Ulemoda la lo e) (melm (list a b €))) “(a lo e el mil mil e E)) 
SN (a iy ©) (lo © cl) (e cl mill) (e mil maily (mii mil e) (mill e i) 


77 A (possibly) more efficient function: 
(defun loop-3-window2 (function list) 
Me (GEO (Gees Lisie) 
(SOM (Pop mEESIE) DD) 
(loop for first = £0 then second 
and second = sO then third 
eval cnie día Jste 
Gown (zonal function irst Second taichi) 





77 A more general function: 
(defun loop-n-window (n function list) 
(HOO PEE Ons eones 
while (nthedr (1= n) x) 
do (apply function (subseq x 0 n)))) 
7; With potentially efficient implementation: 





(define-compiler-macro loop-n-window (n function list whole w) 
(if (typep n '(integer 1 $+.call-arguments-limit)) 
(let ((vars (loop repeat n collect (gensym))) 
(varsO (loop repeat (1- n) collect (gensym))) 
(lst (gensym))) 
“(lee (i lsr piirat) 
(ler p (doop tor y iin varst collect (pv (as lerhi) 
(loop for 
¿Qíloss for YO iim varst tor (Y va) on vars 
collect v collect '= collect v0 collect 'then collect vn 
collect 'and) 
p lear (last yars) im y sie 
do y (sean lene. (come Function) (es "Eumcción (Car Eume Toa) )) 





Read LOOP, a Common Lisp macro for iteration online: https://riptutorial.com/common- 
lisp/topic/1369/loop--a-common-lisp-macro-for-iteration 
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Chapter 20: macros 


Remarks 


The Purpose of Macros 


Macros are intended for generating code, transforming code and providing new notations. These 
new notations can be more suited to better express the program, for example by providing 
domain-level constructs or entire new embedded languages. 


Macros can make source code more self-explanatory, but debugging can be made more difficult. 
As a rule of thumb, one should not use macros when a regular function will do. When you do use 
them, avoid the usual pitfalls, try to stick to the commonly used patterns and naming conventions. 





Macroexpansion Order 


Compared to functions, macros are expanded in a reverse order; outmost first, inmost last. This 
means that by default one cannot use an inner macro to generate syntax required for an outer 
macro. 





Evaluation Order 


Sometimes macros need to move user-supplied forms around. One must make sure not to change 
the order in which they are evaluated. The user may be relying on side effects happening in order. 





Evaluate Once Only 


The expansion of a macro often needs to use the value of the same user-supplied form more than 
once. It is possible that the form happens to have side-effects, or it might be calling an expensive 
function. Thus the macro must make sure to only evaluate such forms once. Usually this will be 
done by assigning the value to a local variable (whose name is censymed). 








Functions used by Macros, using EVAL- 
WHEN 


Complex macros often have parts of their logic implemented in separate functions. One must 
remember, however, that macros are expanded before the actual code is compiled. When 
compiling a file, then by default, functions and variables defined in the same file will not be 
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available during macro execution. All function and variable definitions, in the same file, used by a 
macro must be wrapped inside an evai-waen-form. The evat-wuen should have all three times 
specified, when the enclosed code also should be evaluated during load and runtime. 





























(eval-when (:compile-toplevel :load-toplevel :execute) 
(cerua foobar Y <<...) 


This does not apply to functions called from the expansion of the macro, only the ones called by 
the macro itself. 


Examples 


Common Macro Patterns 


TODO: Maybe move the explanations to remarks and add examples separately 


FOOF 


In Common Lisp, there is a concept of Generalized References. They allow a programmer to setf 
values to various "places" as if they were variables. Macros that make use of this ability often have 
a r-postfix in the name. The place is usually the first argument to the macro. 

















Examples from the standard: tncr, DECF, ROTATEF, SHIFTF, REMF. 


A silly example, a macro that flips the sign of a number store in a place: 


(defmacro flipf (place) 
(Space place) 


WITH-FOO 


Macros that acquire and safely release a resource are usually named with a wits--prefix. The 
macro should usually use syntax like: 





(with-foo (variable details-of-the-foo...) 
DOCE) 





Examples from the standard: wI TH-OPEN-FILE, WITH-OPEN-STREAM, WITH-INPUT-FROM-STRING, WITH-OUTPUT- 

















TO-STRING. 


One approach to implementing this type of macro that can avoid some of the pitfalls of name 
pollution and unintended multiple evaluation is by implementing a functional version first. For 
instance, the first step in implementing a with-widget macro that safely creates a widget and 
cleans up afterward might be a function: 


https://riptutorial.com/ 73 


(defun call-with-widget (args function) 








(let ((widget (apply #'make-widget args))) ; obtain WIDGET 
(unwind-protect (funcall function widget) ; Call FUNCTION with WIDGET 
(cleanup widget) ; cleanup 


Because this is a function, there are no concerns about the scope of names within function or 
supplier, and it makes it easy to write a corresponding macro: 


(defmacro with-widget ((var &rest args) &body body) 
`” (call-with-widget (list ,@args) (lambda (,var) ,@body))) 


DO-FOO 


Macros that iterate over something are often named with a bo-prefix. The macro syntax should 
usually be in form 





(do-foo (variable the-foo-being-done return-value) 
BOYA) 


Examples from the standard: borimes, DOLIST, DO-SYMBOLS. 


FOOCASE, EFOOCASE, CFOOCASE 


Macros that match an input against certain cases are often named with a casz-postfix. There is 
often a £...case-variant, which signals an error if the input doesn't match any of the cases, and 
c...case, which signals a continuable error. They should have syntax like 


























(foocase input 





(case-to-match-against (optionally-some-params-for-the-case) 
case-body-forms...) 
more-cases... 





[ (otherwise otherwise-body)]) 








Examples from the standard: cass, TYPECASE, HANDLER-CASE. 























For example, a macro that matches a string against regular expressions and binds the register 
groups to variables. Uses CL-PPCRE for regular expressions. 


(defmacro regexcase (input &body cases) 
(let ((block-sym (gensym "block") ) 
(input-sym (gensym "input"))) 








“(et ((,imoueE=Svm y Layouts) ) 
(block ,block-sym 
¿GQ (loop for (regex vars . body) in cases 
if (eql regex 'otherwise) 
collect * (return-from ,block-sym (proga ,vars ,@body) ) 
else 
collect * (cl-ppcre:register-groups-bind ,vars 


(regex ,input-sym) 
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(return-from ,block-sym 
(progn ,@body)))))))) 


(defun test (input) 
(regexcase input 
("(NNd+)=(ANd+)" (foo bar) 


(format E "Foot =a, Bar: =as$" foo bar) ) 
("Foo: (\\wt)$" (foo) 
(Formar e ios ray Y oO) ) 


(otherwise (format t "Didn't match.~%")))) 


(test "asd 23-234 qwe") 
9 WOO? BS, Bees 234 
(test "Foo: Foobar") 

T BOGS POODE, 

(test "Eso: 42 = E") 

eo Daleln e meten, 


DEFINE-FOO, DEFFOO 


Macros that define things are usually named either with perine- or per -prefix. 























Examples from the standard: DEFUN, DEFMACRO, DEFINE-CONDITION. 




















Anaphoric Macros 


An Anaphoric Macro is a macro that introduces a variable (often rr) that captures the result of a 
user-supplied form. A common example is the Anaphoric If, which is like a regular tr, but also 
defines the variable 17 to refer to the result of the test-form. 


(defmacro aif (test-form then-form optional else-form) 
"(let ((it ,test-form)) 
(dí de piclasin=irorm pElse=toma))) 





(defun test (property plist) 
(aif (getf plist property) 
(format t "The value of ~s is ~a.~%" property it) 
(format t "~s wasn't in ~s!~%" property plist) )) 


(test caia EO sio Z0 ae So 
Mas Welle oie GIA ais) 1G), 

(Cese g6 iS MO so Z0 So SO) 

a 3D mesa im (3A 10 313 20 35€ SON 


MACROEXPAND 


Macro expansion is the process of turning macros into actual code. This usually happens as part 
of the compilation process. The compiler will expand all macro forms before actually compiling 
code. Macro expansion also happens during interpretation of Lisp code. 


One can call uacrozxeann manually to see what a macro form expands to. 
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CL-USER> (macroexpand '(with-open-fi1l (rle Wrot) 
(do-something-with file))) 
(ES EE (OPENS OE C S 

(UNWIND-PROTECT 
(MULTIPLE-VALUE-PROG1 (PROGN (DO-SOMETHING-WITH FILE 
(WHEN FILE (CLOSE FILE :ABORT #:G725)))) 





















































n 





ETO #:G725 NIL)) 





























MACROEXPAND-1 is the same, but only expands once. This s useful when trying to make sense of a 
macro form that expands to another macro form. 





CL-USER> (macroexpand-1 '(with-open-fil (Erle Hoon) 





(do-something-with file))) 
(WITH-OPEN-STREAM (FILE (OPEN "foo")) (DO-SOMETHING-WITH FILE 



































Note that neither macroexpanb Nor macroexpann-1 expand the Lisp code on all levels. They only 
expand the top-level macro form. To macroexpand a form fully on all levels, one needs a code 
walkerto do so. This facility is not provided in the Common Lisp standard. 


Backquote - writing code templates for macros 


Macros return code. Since code in Lisp consists of lists, one can use the regular list manipulation 
functions to generate it. 


77 A pointless macro 
(defmacro echo (form) 
(List "proga 
(ligt “Eommee t Pronn sas" (list “quere Form) ) 
form) ) 


This is often very hard to read, especially in longer macros. The Backquote reader macro allows 
one to write quoted templates that are filled in by selectively evaluating elements. 


(defmacro echo (form) 
` (progn 
(former © “orm: Sas" V form) 
p EOT) 


(macroexpand ' (echo (+ 3 4))) 
¡=> (PROGN (FORMAT T "Form: ~a~%" '(+ 3 4)) (+ 3 4)) 


This version looks almost like regular code. The commas are used to evaluate rorm; everything 


else is returned as is. Notice that in ', form the single quote is outside the comma, so it will be 
returned. 


One can also use ,¢ to splice a list in the position. 


(defmacro echo (&rest forms) 
` (progn 
,C (lees for romu im forms collece ~ (emer + Vonn, sacs , om) ) 
,@£orms) ) 


(macroexpand '(echo (+ 3 4) 
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(Parto Ons) 
(random 10))) 





FORMA UE Orme a E ÓN 
FORMA "Porm: as +" (PRINT "Eso "y, 
FORMA "Form: ~a~%" (RANDOM 10)) 

















Backquote can be used outside macros too. 
Unique symbols to prevent name clashes in macros 


The expansion of a macro often needs to use symbols that weren't passed as 


arguments by the 


user (as names for local variables, for example). One must make sure that such symbols cannot 


conflict with a symbol that the user is using in the surrounding code. 


This is usually achieved by using censy™, a function that returns a fresh uninterned symbol. 





Bad 





Consider the macro below. It makes a Dorimes-loop that also collects the result of the body into a 


list, which is returned at the end. 


(defmacro dotimes+collect ((var count) &body body) 
STA ES SM EST) 
(dotimes (,var ,count (nreverse result) ) 
(push (progn ,@body) result)))) 


(dotimes+collect (i 5) 


o 


Gomme E o) 


This seems to work in this case, but if the user happened to have a variable name resuLr, which 


they use in the body, the results would probably not be what the user expects. 
attempt to write a function that collects a list of sums of all integers up to x: 


(defun sums-upto (n) 
(let ((result 0)) 
(dotimes+collect (i n) 
Gmer trest eaan) 





(sumsSupto 10) ;=> Error! 


Good 


To fix the problem, we need to use cexsym to generate a unique name for the z: 
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Consider this 


ÉEsunT-Variable in the 


af 


macro expansion. 


(defmacro dotimes+collect ((var count) &body body) 
(let ((result-symbol (gensym "RESULT"))) 
er (( zesule=s also (List) )) 
(dotimes (,var ,count (nreverse ,result-symbol)) 








(push (progn ,@body) ,result-symbol))))) 


(SUS SUECO) (0 1 3 G Ie ts 2 2a 36 45) 
TODO: How to make symbols from strings 
TODO: Avoiding problems with symbols in different packages 
if-let, when-let, -let macros 
These macros merge control flow and binding. They are an improvement over anaphoric 


anaphoric macros because they let the developer communicate meaning through naming. As such 
their use is recommended over their anaphoric counterparts. 





(if-let (user (get-user user-id) ) 
(show-dashboard user) 
(redirect 'login-page)) 


FOO-LET Macros bind one or more variables, and then use those variables as the test form for the 
corresponding conditional (rr, waen). Multiple variables are combined with ann. The chosen branch 
is executed with the bindings in effect. A simple one variable implementation of 1r-1er might look 
something like: 











(defmacro if-let ((var test-form) then-form &0ptional else-form) 
“(let ((,var ,test—form) ) 





(if ,var ,then-form ,else-form))) 


(Macro sx pan EM (cam (Geile tamu E O AO CES 0) YD) 
onnar ARES a) 
(format t "Not found.~%") )) 




















5 (ane (GA (emir Y (aA 10 32 20 3 30) AO) 
; (IF A 

5 (FORMA WA O) 

$ (FORMA Mer koumo auh) 





A version that supports multiple variables is available in the Alexandria library. 
Using Macros to define data structures 


A common use of macros is to create templates for data structures which obey common rules but 
may contain different fields. By writing a macro, you can allow the detailed configuration of the 
data structure to be specified without needing to repeat boilerplate code, nor to use a less efficient 
structure (such as a hash) in memory purely to simplify programming. 


For example, suppose that we wish to define a number of classes which have a range of different 
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properties, each with a getter and setter. In addition, for some (but not all) of these properties, we 
wish to have the setter call a method on the object notifying it that the property has been changed. 
Although Common LISP already has a shorthand for writing getters and setters, writing a standard 
custom setter in this way would normally require duplicating the code that calls the notification 
method in every setter, which could be a pain if there are a large number of properties involved. 
However, by defining a macro it becomes much easier: 


(defmacro notifier (class slot) 
"Defines a setf method in (class) for (slot) which calls the object's changed method." 
" (defmethod (setf ,slot) (val (item ,class)) 
(setf (slot-value item ',slot) val) 
(changed item ',slot))) 





(defmacro notifiers (class slots) 
"Defines setf methods in (class) for all of (slots) which call the object's changed method." 
` (progn 
,@ (loose for se ain slors collectime ~ (moemitiker elass ¿8)))) 








(defmacro defclass-notifier-slots (class nslots slots) 
"Defines a class with (nslots) giving a list of slots created with notifiers, and (slots) 
giving a list of slots created with regular accessors." 
` (progn 
(defclass ,class () 
Cotílsos fos s a mslors collecting * (8 reader pa) 
logs Foz s am slots collectinme * (Ss sacesssor ,¿8)))) 
morn iers elass nS oE 





We can now write (defclass-notifier-slots foo (bar baz qux) (waldo)) and immediately define a 
class foo with a regular slot walao (created by the second part of the macro with the specification 
(waldo :accessor waldo)), and slots bar, baz; and qux with setters that call the changed method 
(where the getter is defined by the first part of the macro, (bar :reader bar), and the setter by the 
invoked notifier macro). 


In addition to allowing us to quickly define multiple classes that behave this way, with large 
numbers of properties, without repetition, we have the usual benefit of code reuse: if we later 
decide to change how the notifier methods work, we can simply change the macro, and the 
structure of every class using it will change. 


Read macros online: https://riptutorial.com/common-lisp/topic/1257/macros 
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Chapter 21: Mapping functions over lists 


Examples 


Overview 


A set of high-level mapping functions is available in Common Lisp, to apply a function to the 
elements of one or more lists. They differ in the way in which the function is applied to the lists and 
how the final result is obtained. The following table summarize the differences and shows for each 
of them the equivalent LOOP form. fis the function to be applied, that must have a number of 
arguments equal to the number of lists; “applied to car” means that it is applied in turn to the 
elements of the lists, “applied to cdr” means that it is applied in turn to the lists, their cdr, their cddr, 
etc.; the “returns” column shows if the global result is the obtained by listing the results, 
concatenating them (so they must be lists!), or simply used for side-effects (and in this case the 
first list is returned). 





(mapcar f l4... eat E (loop for xy in ly... for Xp in Ip collect (f xy 
In) .- Xn)) 
(maplist f l4... adr istot results (loop for xq on ly... for Xn on In collect (f xy 
ln) six Xn)) 
(mapcan f l4 E concatenation of (loop for xy in l4... for Xp in In nconc (f xy 
.- In) results ... Xn)) 
(mapcon f l4 eae concatenation of (loop for xq on ly... for Xn ON lIn nconc (f x4 
.- In) results ... Xn)) 
(mapc f ly... In al | (loop for xy in l4... for Xp in In do (f X4... Xn 
) 1 ) finally (return 14)) 

l f l4... f l f X4... 
iaoi lecia | ede h (loop for xq on ly... for Xn on In do (f xy 


Xn) finally (return l4)) 


Note that, in all the cases, the lists can be of different lengths, and the application terminates when 
the shortest list is terminated. 


Another couple of map functions are available: map, that can be applied to sequences (strings, 
vectors, lists), analogous to mapcar, and that can return any type of sequence, specified as first 
argument, and map-into, analogous to map, but that destructively modifies its first sequence 
argument to keep the results of the application of the function. 
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Examples of MAPCAR 


MAPCAR is the most used function of the family: 

















C USER Mape ane (AS) 

(2 3 4) 

CAUSER (Mapas OS AS) VY (DEN 

((i 5 AY) (2 = 1B) (8 y) ©€)) 

CL-USER> (mapcar (lambda (x y z) (+ (* x y) 2)) 
EAS») 
“(10 20 30) 
"(100 200 300)) 


(ARO Z 40390) 
CAUSE ec AS (O ECC IN oa dono Clans list 
(mapcar #'cdr 
(sort (mapcar (lambda (x) 
(cons (random 100) x)) 
Sia) 





#'<= 
:key #'car))) 
(lL DAG B HOE © F) 





An idiomatic use of mapcar is to transpose a matrix represented as a list of lists: 


CL-USER> (defun transpose (list-of-lists) 
(apply #'mapcar #'list list-of-lists)) 





ROTATE 
Cl USHER (esas @'S Cums (DAS (e) (o Ba) 
(CADA SN MSIE (CARETO) O) 
































a a E a 
; A |B © A D E 
e SO Ser Sees 
E D E E becomes B E H 
9 ibso=é A ZO A 
; G H i E E JE 
A a 














For an explanation, see this answer. 


Examples of MAPLIST 





CESUSER (imejollasie (Aaa do Si) (E OSOS A (l 2 3 4)))) 
((@ 1 23 4) (0 23 4) (© & 4) (0 4)) 
CL-USER> (maplist #'append 
Mier To @ el =) 
23) 
(A 38 € p= 1 2 3) ERC 2 8) (CAD = 38))) 











Examples of MAPCAN and MAPCON 


MAPCAN: 





CL-USER> (mapcan #'reverse '((1 2 3) (a bc) (100 200 300))) 
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(3 2 LECIA 300 200 100) 

















CL-USER> (defun from-to (min max) 
(lows for a from mim ro mes: collect y) 
FROM-TO 
CE-USER> (Erom=to L 5) 
(MSI) 
CAU SER Map San ao LS) V(S & &)) 
( 


IS 5 234 5 3 ES) 


One of the uses of MAPCAN is to create a result list without NIL values: 


CE-USER> (let (C(O ZORA) DS) 
(mapcan (lambda (x) 
(1f (member x 11) 
(rsi sz) 
mL) 
T2 do 12 1d 16 18 20 
Le 16 14d 127 10 3 6 4 2))) 

















(GEOR ARO) 
MAPCON: 
CL-USER> (mapcon +'copy-list '(1 2 3)) 
(l 23 2 3 3) 
Cl USER as (Matec orem anto d AI) ESE Sn te lage el) AS EAU (OCN (CER) E) 
(Asses) 


Examples of MAPC and MAPL 








MAPC: 
Gl USER sa (nee. em leno cl ME a E A (Lee) i) 
dl 
4 
9 
16 
G 2 3 4) 
CL-USER> (let ((sum 0)) 
mape (lambda (x y) (incf sum (* x y))) 
IES) 
"(LOS 200 00) ) 
sum) 


L400 p = (Cl xe 100) tw (2 x ZOO) wz (3 x SOO) 





CHE USER ae map ie (alicia cl igus (HG Sites) A pa SU Ems tact si) C e) 
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Read Mapping functions over lists online: https://riptutorial.com/common-lisp/topic/6064/mapping- 
functions-over-lists 
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Chapter 22: Pattern matching 


Examples 


Overview 


The two main libraries providing pattern matching in Common Lisp are Optima and Trivia. Both 
provide a similar matching API and syntax. However trivia provides a unified interface to extend 
matching, defpattern. 


Dispatching Clack requests 


Because a clack request is represented as a plist, we can use pattern matching as the entry point 
to the clack app as a way to route request to their appropriate controllers 


(defvar *app* 
(lambda (env) 
(match env 
((plist :request-method :get 
:request-uri uri) 
(match uri 
("/" (top-level)) 
((ppcre "/tag/(\\wt)/$" name) (tag-page name))))))) 





Note: To start *app* we pass it to clackup. ej (clack:clackup *app*) 
defun-match 
Using pattern matching one can intertwine function definition and pattern matching, similar to SML. 


(trivia:defun-match fib (index) 





"Return the corresponding term for INDEX." 

(0 1) 

(1 1) 

(aces (6 (Ena (GES imee (Guo (E imee 2))) ) ) 


(Eia 5) 
if => $ 


Constructor patterns 
Cons-cells, structures, vectors, lists and such can be matched with constructor patterns. 


(hoes tor 1 trom i to 30 
do (format t "~5<~a~;~>" 
(match (cons (mod 1 3) 
(mod i 5)) 
(ícoms 0 0) unalone) 
( (errors: 0) _)) EE ZE 000) 
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(cons _ 161 "Buzz" 


(ME 


when (zerop (mod i 5)) do (terpri)) 
a Al 2 pipz 4 Buzz 
p Pizz Y 8 Fizz Buzz 


p A wizz L3 14 Fizzbuzz 
7 ALG EY is L9 Buzz 
A Eigr 22 23 Bizz Buzz 
9 26 Fizz 28 29 ENZZDUZZ 


Guard-pattern 
Guard patterns can be used to check that a value satisfies an arbitrary test-form. 


(dotimes (1 5) 
(Format. € "ed: ~a~s" 
i (match i 
((ouiersol $ (eee =) Ocb aus) 








(C “Even!™))))) 
¿ O: Even! 
p ila Oclel! 
Wee Even! 
SEO El cll 
; 4: Even! 


Read Pattern matching online: https://riptutorial.com/common-lisp/topic/2933/pattern-matching 
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Chapter 23: Quote 


Syntax 


e (quote object) -> object 


Remarks 


There are some objects (for example keyword symbols) that don't need to be quoted since they 
evaluate to themselves. 


Examples 


Simple quote example 


Quote is a special operator that prevents evaluation of its argument. It returns its argument, 
unevaluated. 


Q 
7 

El 
u 


ER> (quote a) 











CL-USER> (let ((a 3)) 
(quote a)) 





"is an alias for the special operator QUOTE 


The notation 'thing is equal to (quote thing). 


The reader will do the expansion: 


> (resd=tromestrcliasg "a 
(QUOTE A) 





Quoting is used to prevent further evaluation. The quoted object evaluates to itself. 


v 
w 


If quoted objects are destructively modified, the consequences are undefined! 


Avoid destructive operations on quoted objects. Quoted objects are literal objects. They are 
possibly embedded in the code in some way. How this works and the effects of modifications are 
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unspecified in the Common Lisp standard, but it can have unwanted consequences like modifying 
shared data, trying to modify write protected data or creating unintended side-effects. 


Hee 50455 
Quote and self-evaluating objects 


Note that many datatypes don't need to be quoted, since they evaluate to themselves. ovore is 
especially useful for symbols and lists, to prevent evaluation as Lisp forms. 





Example for other datatypes not needed to be quoted to prevent evaluation: strings, numbers, 
characters, CLOS objects, ... 


Here an example for strings. The evaluation results are strings, whether they are quoted in the 
source or not. 


> (lee ((some=stiinme=1 "dais as) a serie") 





some-string-2 '"this is a string with a quote in the source") 





( 
( 
(some-string-3 (quote "this is another string with a quote in the source"))) 
E 








(lis 





some-string-1 some-string-2 some-string-3)) 


(Urais le & String 





"this is a string with a quote in the source" 





"this is another string with a quote in the source") 


Quoting for the objects thus is optional. 


Read Quote online: https://riptutorial.com/common-lisp/topic/1315/quote 
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Chapter 24: Recursion 


Remarks 


Lisp is often used in educational contexts, where students learn to understand and implement 
recursive algorithms. 


Production code written in Common Lisp or portable code has several issues with recursion: They 


do not make use of implementation-specific features like tail call optimization, often making it 
necessary to avoid recursion altogether. In these cases, implementations: 


e Usually have a recursion depth limit due to limits in stack sizes. Thus recursive algorithms 
will only work for data of limited size. 

e Do not always provide optimization of tail calls, especially in combination with dynamically 
scoped operations. 

* Only provide optimization of tail calls at certain optimization levels. 

e Do not usually provide tail call optimization. 

e Usually do not provide tail call optimization on certain platforms. For example, 
implementations on JVM may not do so, since the JVM itself does not support tail call 
optimization. 


Replacing tail calls with jumps usually makes debugging more difficult; Adding jumps will cause 
stack frames to become unavailable in a debugger. As alternatives Common Lisp provides: 


e Iteration constructs, like po, porimes, Loor, and others 
e Higher-order functions, like mar, kenuce, and others 
e Various control structures, including low-level go to 

















Examples 
Recursion template 2 multi-condition 


(defun fn (x) 
(cond (test-conditionl the-valuel) 
(test-condition2 the-value2) 





(t (fn reduced-argument-Xx)))) 


CL-USER 2788 > (defun my-fib (n 


) 
(CONAM (AA L) 
Me a 2) 1) 
(e Gr 
(yt (= im AL) )) 
(@y=ills (= im 2)))))) 


Mi Beis) 
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C USERRA 7S9 m (1 o) 





C USERRA ON (10 os) 





CE USERRA O (1 OS) 





CH USERRA E > (mys e bA) 





C USERRA O SN y RS 





CH USERRA 918 (mys DRO) 

















C USERRA OSE y OA) 





Recursion template 1 single condition single tail recursion 


(defun fn (x) 
(cond (test-condition the-value) 





(t (fn reduced-argument-X)))) 


Compute nth Fibonacci number 


7;Find the nth Fibonacci number for any n > 0. 
7; Precondition: n > 0, n is an integer. Behavior undefined otherwis 





(defun fibonacci (n) 
(cond 
( ;; Base case. 


; The first two Fibonacci numbers (indices 1 and 2) are 1 by definition. 


i 
(<= n 2) pp LE m <= 2 
1 jp then return 1, 


(t 7; else 
(+ 7; return the sum of 
7; the results of calling 
(Eilcomacca (= im il))) pe Fibonacci (m-i) anc 
(Ercoonecei (= m 2)) Ae Gona ceninin e 
;; This is the recursive cas 





Recursively print the elements of a list 


;;Recursively print the elements of a list 
(defun print-list (elements) 
(cond 








((null elements) '()) ;; Base case: There are no elements that have yet to be printed. 


Don't do anything and return a null list. 
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(t 
;; Recursive case 
7; Print the next element. 





(write-lin (write-to-string (car elements) ) ) 
;; Recurse on the rest of the list. 





(print-list (cdr elements) ) 


To test this, run: 


(seta test lis NA ES ANN) 
(Perle lts ut Ss cities E) 


The result will be: 


5 WwWN E 


Compute the factorial of a whole number 
One easy algorithm to implement as a recursive function is factorial. 


7;Compute the factorial for any n >= 0. Precondition: n >= 0, n is an integer. 
(defun factorial (n) 


0) 1) ;; Special case, 0! = 1 
15) A) $9 Base case, 11 = 1 


;; Recursive case 
pp Mileagols im oy telas taciorilal o in = il. 
(= m EE CTO (= m i1)))))) 


Read Recursion online: https://riptutorial.com/common-lisp/topic/3190/recursion 
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Chapter 25: Regular Expressions 


Examples 


Using with pattern matching to bind captured groups 


The pattern matching library trivia provides a system trivia.ppcre that allows captured groups to 
be bound through pattern matching 


(trivia:match "John Doe" 





((trivia.ppcre:ppcre "(.*)\\W+(.*)" first-name last-name) 





(list :first-name first-name :last-name last-name))) 


;; => (:FIRST-NAME "John" :LAST-NAME "Doe") 








+ Note: the library Optima provides a similar facility in the system optima. ppere 


Binding register groups with CL-PPCRE 





CL-PPCRE : REGISTER-GROUPS-BIND Will match a string against a regular expression, and if it matches, 
bind register groups in the regex to variables. If the string does not match, wrx is returned. 














(defun parse-date-string (date-string) 





(cl-ppcre:register-groups-bind 
(year month day) 
(MAN) (Mea) (Aaa) claros ing) 
(list year month day))) 


(Parse Jare simi q O ON OE UCSI) 
(parse-date-string "foobar") ¡=> NIL 
(parse-date-string "2016-7-23") ¡=> NIL 





Read Regular Expressions online: https://riptutorial.com/common-lisp/topic/2897/regular- 
expressions 
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Chapter 26: sequence - how to split a 
sequence 


Syntax 


1. split regex target-string &key start end limit with-registers-p omit-unmatched-p sharedp => 
list 

2. lispworks:split-sequence separator-bag sequence &key start end test key coalesce- 
separators => sequences 

3. split-sequence delimiter sequence ¿key start end from-end count remove-empty-subseqs 
test test-not key => list of subsequences 


Examples 


Split strings using regular expressions 


The library CL-PPCRE provides the function spiit which allows us to split strings in substrings that 
match a regular expression, discarding the parts of the string that do not. 


(cl=aecres soli MA, Y 1M127,0.0)., 10) 
=> a pp won pel ae 


SPLIT-SEQUENCE in LispWorks 


Simple split of an IP number string. 


> (Mismos: solle=secquences Yo "127.0,.0.1W) 
(e Op mon ey 


Simple split of an URL: 


> (lispvorks:spilit=-secuence Y EZ t/t OO PM o) arnes 
:Coalesce-separators t) 
(Mito MISA on moyn "yn NOON "mhar" MEL 


Using the split-sequence library 


The split-sequence library provides a function sp1it-sequence, Which allows to split on elements of 
a sequence 


(split-sequence:split-sequence #\Space "John Doe II") 
9 A => ("John” UND ee MERO 


Read sequence - how to split a sequence online: https://riptutorial.com/common- 
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lisp/topic/1454/sequence---how-to-split-a-sequence 
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Chapter 27: Streams 


Syntax 





=> character 


e (read-char optional stream eof-error-p eof-value recursive-p 


e (write-char character soptional stream) => character 





e (read-line £optional stream eof-error-p eof-value recursive-p 


=> line, missing-newline-p 


e (write-line line £optional stream) => line 


Parameters 


stream The stream to read from or write to. 


eof-error— 


a Should an error be signalled if end of file is encountered. 


eof-value What value should be returned if eof is encountered, and eof-error-p is false. 


recursive- ls the read-operation called recursively from reap. Usually this should be left as 
p NIL. 





character The character to write, or the character that was read. 


line The line to write, or the line that was read. 


Examples 


Creating input streams from strings 





The macro wirs-ineur-rrom-srrine Can be used to make a stream from a string. 


(With inpuES from sis) lerte Boobs) 
(Logs fom a from © 
for char = (read-char str nil nil) 
while char 
de (ormat e Wes === 51 al (clase) ))) 


The same can be done manually using MAkE-STRING-INPUT-STREAM. 
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(let ((str (make-string-input-stream "Foobar"))) 
(Los for al fron © 
for char = (read char str nil nil) 
while char 
domir ornar ic "eds seats") al lac) }) )) 


Writing output to a string 





The macro wirs-oureur-ro-srrine Can be used to create a string output stream, and return the 
resulting string at the end. 


(with-output-to-string (str) 
(write-line "Foobar!" str) 
(write-string "Barfoo!" str) ) 

¡=> "Foobar! 

A Bartoo!" 























The same can be done manually using vmaxe-strIiNG-OUTPUT-STREAM ANd GET-OUTPUT-STREAM-STRING. 





(let ((str (make-string-output-stream))) 
(write-line "Foobar!" str) 
(wellteSsituing Baroo srr) 





(get-output-stream-string str)) 


Gray streams 


Gray streams are a non-standard extension that allows user defined streams. It provides classes 
and methods that the user can extend. You should check your implementations manual to see if it 
provides Gray streams. 


For a simple example, a character input stream that returns random characters could be 
implemented like this: 


(defclass random-character-input-stream (fundamental-character-input-stream) 
((character-table 
:initarg :character-table 
:initform "abcdefghijklmnopqrstuvwxyz 
" ; The newline is necessary. 





:accessor character-table) ) 
(:documentation "A stream of random characters.") ) 


(defmethod stream-read-char ((stream random-character-input-stream)) 
(let ((table (character-table stream))) 
(aref table (random (length table))))) 


(let ((stream (make-instance 'random-character-input-stream))) 
(dotimes (i 5) 
(print (read-line stream)))) 
; "gyaexyfjsqdcpciaaftoytsygdeycrrzwivwcfb" 
7 “gctnoxpajovjqjbkiqykdflbhfspmexjaaggonhydhayvknwpdydyiabithpt" 
¿ "nvíxwzczfalosaqw" 
; “sxeliejcovrtesbpmoppfvvjfvx" 
7 “hjplaqgstbodbalnmxhsvxdox" 
¿=> NIL 
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Reading file 


A file can be opened for reading as a stream using wirs—op 





(GELT 
(Logs oz a from © 


(with-open-fi1l #P"test.file") 


Ba IL 








oie dam (read-lin fall sat )) 
while line 
Glo (Gromer e Wes sa 


: Foobar 


i line))) 


a DELEDO 

: Quuxbar 
: Barquux 
: Quuxfoo 
: Fooquux 


The same can be done manually using oven and ciose. 











(let ((file (open #P"test.file") ) 
(aborted t)) 
(unwind-protect 
(progn 
(logs Eer a zom 0) 








Bow IL atin (zeacd=-lina Sile mil miiy 
while line 
de (Eormet L "de mamma 
(setf aborted nil)) 


:abort aborted))) 


i line)) 


(close file 





Note that R 





EAD-LIN 








CL. 


Writing to a file 





z creates a new string for each line. 
provide a variant, which can read a line into a string buffer. Example: x 


= Macro. 





EN-FIL 








This can be slow. Some implementations 
¿ro for Allegro 





EAD-LIN 











A file can be opened for writing as a stream using :14-oren-"118 macro. 

















(with-open-file (file #P"test.file" :direction :output 
:if-exists :append 
:1f-does-not-exist :create) 
(close (line (Moca: raros" "Ownwsdosia" 
"Barquux" "Quuxfoo" "Fooquux") ) 
(write-line line file))) 
The same can be done manually with open and cios». 
(let ((file (open #P"test.file" :direction :output 
:if-exists :append 
:if-does-not-exist :create))) 
(delist. (incre EOS O) INE o OO UU ala 
"Barquux" "Quuxfoo" "Fooquux") ) 
(write-line line file) ) 





(close file) ) 
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Copying a file 
Copy byte-per-byte of a file 


The following function copies a file into another by performing an exact byte-per-byte copy, 
ignoring the kind of content (which can be either lines of characters in some encoding or binary 
data): 


(defun byte-copy (infile outfile) 
(with-open-file (instream infile :direction :input :element-type '(unsigned-byte 8) 
[lf—does not exist mill) 


(when instream 








(with-open-file (outstream outfile :direction :output :element-type '(unsigned-byte 8) 
:if-exists :supersede) 
(MoopREo O (read-byte instream nil) 
while byte 


do (write-byte byte outstream)))))) 


The type (unsigned-byte 8) is the type of 8-bit bytes. The functions read-byte and write-byte work 
on bytes, instead Of read-char and write-char that work on characters. read-byte returns a byte 
read from the stream, or nzr at the end of the file if the second optional parameter is nz (otherwise 
it signals an error). 


Bulk copy 


An exact copy, more efficient the the previous one. can be done by reading and writing the files 
with large chunks of data each time, instead of single bytes: 


(defun bulk-copy (infile outfile) 
(with-open-file (instream infile :direction :input :element-type '(unsigned-byte 8) 
“IE =does>not>=exust nilo) 
(when instream 
(with-open-file (outstream outfile :direction :output :element-type '(unsigned-byte 8) 
:if-exists :supersede) 
(let ((buffer (make-array 8192 :element-type '(unsigned-byte 8)))) 








(loop for bytes-read (read-sequence buffer instream) 
while (plusp bytes-read) 








do (write-sequence buffer outstream :end bytes-read))))))) 


read-sequence ANO write-sequence are used here with a buffer which is a vector of bytes (they can 
operate on sequences of bytes or characters). read-sequence fills the array with the bytes read 
each time, and returns the numbers of bytes read (that can be less than the size of the array when 
the end of file is reached). Note that the array is destructively modified at each iteration. 


Exact copy line-per-line of a file 


The final example is a copy performed by reading each line of characters of the input file, and 
writing it to the output file. Note that, since we want an exact copy, we must check if the last line of 
the input file is terminated or not by an end of line character(s). For this reason, we use the two 
values returned by read-1ine: a new string containing the characters of the next line, and a 
boolean value that is true if the line is the last of the file and does not contain the final newline 
character(s). In this case write-string is used instead of write-1ine, since the former does not add 
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a newline at the end of the line. 


(defun line-copy (infile outfile) 
(with-open-file (instream infile :direction :input :if-does-not-exist nil) 
(when instream 
(with-open-file (outstream outfile :direction :output :if-exists :supersede) 
(let (line missing-newline-p) 
(Loop 
(multiple-value-setq (line missing-newline-p) 





(read-line instream nil nil)) 








(cond (missing-newline-p ; we are at th nd of file 
(when line (write-string line outstream)) ; note "write-string' 
(return) ) ; exit from simple loop 


(t (write-line line outstream))))))))) 


Note that this program is platform independent, since the newline character(s) (varying in different 
operating systems) is automatically managed by the read-1ine and mrite-1ine functions. 


Reading and writing entire files to and from strings 


The following function reads an entire file into a new string and returns it: 





(defun read Fiii (infile) 
(with-open-file (instream infile :direction :input :if-does-not-exist nil) 
(when instream 
(let ((string (make-string (file-length instream)))) 
(read-sequence string instream) 
string)))) 


The result is wrt if the file does not exists. 


The following function writes a string to a file. A keyword parameter is used to specify what to do if 
the file already exists (by default it causes an error, the values admissible are those of the witn- 
open-file macro). 


(defun write-file (string outfile key (action-if-exists :error) ) 





(check-type action-if-exists (member nil :error :new-version :rename :rename-and-delet 
:Overwrite :append :supersede)) 
(with-open-file (outstream outfile :direction :output :if-exists action-if-exists) 
(write-sequence string outstream))) 


In this case write-sequence Can be substituted with write-string. 


Read Streams online: https://riptutorial.com/common-lisp/topic/3028/streams 
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Chapter 28: Types of Lists 


Examples 


Plain Lists 


Plain lists are the simplest type of list in Common Lisp. They are an ordered sequence of 
elements. They support basic operations like getting the first element of a list and the rest of a list 
in constant time, support random access in linear time. 


(Lise 1 2 3) 
=> (1 2 3) 


(Fiesic (list L 2 3)))) 
=> il 


(est (lis. 1 2 27) 
O) 


There are many functions that operate on "plain" lists, insofar as they only care about the 
elements of the list. These include find, mapcar, and many others. (Many of those functions will 
also work on 17.1 Sequence Concepts for some of these functions. 


Association Lists 


Plain lists are useful for representing a sequence of elements, but sometimes it is more helpful to 
represent a kind of key to value mapping. Common Lisp provides several ways to do this, 
including genuine hash tables (see 18.1 Hash Table Concepts). There are two primary ways or 
representing key to value mappings in Common Lisp: property lists and association lists. This 
example describes association lists. 


An association list, or alist is a "plain" list whose elements are dotted pairs in which the car of each 
pair is the key and the cor of each pair is the associated value. For instance, 





(defparameter *ages* (list (cons 'john 34) (cons 'mary 23) (cons 'tim 72))) 


can be considered as an association list that maps symbols indicating a personal name with an 
integer indicating age. It is possible to implement some retrieval functions using plain list functions, 
like member. For instance, to retrieve the age of john, one could write 


(cdr (first (member 'mary *age* :key 'car))) 
p=> 23 


The member function returns the tail of the list beginning with with a cons cell whose car is mary, 
that is, ((mary . 23) (tim . 72)), first returns the first element of that list, which is (mary . 23), and 
cdr returns the right side of that pair, which is 23. While this is one way to access values in an 
association list, the purpose of a convention like association lists is to abstract away from the 
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underlying representation (a list) and to provide higher-level functions for working with the data 
structure. 


For association lists, the retrieval function is assoc, which takes a key, an association list and 
optional testing keywords (key, test, test-not), and returns the pair for the corresponding key: 


(assoc 'tim *ages*) 
ZO) 


Since the result will always be a cons cell if an item is present, if assoc returns nil, then the item 
was not in the list: 


(assoc 'bob *ages*) 
¡=> nil 


For updating values in an association list, setf may be used along with cdr. For instance, when 
john's birthday arrives and his age increases, either of the following could be performed: 
(er: lece asis oc “Jonn vages?) 5) 


(Gimes (cer (assoc "Om wages) 


incf works in this case because it is based on setf. 


Association lists can also be used as a type of bidirectional map, since key to value mappings be 
retrieved based on the value by using the reversed assoc function, rassoc. 


In this example, the association list was created by using list and cons explicitly, but association 
lists can also be created by using pairlis, which takes a list of keys and data and creates an 
association list based on them: 


(pedalis (Sena mesy tia) “(23 07 GAI) 
IS) A (mery > 6D) (eam a G2) 


A single key and value pair can be added to an association list using acons: 


(acoms “sola 23 "( (mary . 67) (eim a 82))) 
=> (Gona . 25) (nery . 67) (eimi s G2) 


The assoc function searches through the list from left to right, which means that is is possible to 
"mask" values in an association list without removing them from a list or updating any of the 
structure of the list, just by adding new elements to the beginning of the list. The acons function is 
provided for this: 

(diaria es patri (SOL maey ica) SS 72)))))) 

(defvar *new-ages* (acons 'mary 29 *ages*)) 

*new-ages* 


¿=> (mary . 29) (Gama «a 34) (mary . 23) (enn = 12)) 
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And now, a lookup for mary will return the first entry: 


(assoc 'mary *new-ages*) 
=> 29 


Property Lists 


Plain lists are useful for representing a sequence of elements, but sometimes it is more helpful to 
represent a kind of key to value mapping. Common Lisp provides several ways to do this, 
including genuine hash tables (see 18.1 Hash Table Concepts). There are two primary ways or 
representing key to value mappings in Common Lisp: property lists and association lists. This 
example describes property lists. 


A property list, or plist, is a "plain" list in which alternating values are interpreted as keys and their 
associated values. For instance: 


(defparameter *ages* (list 'john 34 'mary 23 'tim 72)) 





can be considered as a property list that maps symbols indicating a personal name with an integer 
indicating age. It is possible to implement some retrieval functions using plain list functions, like 
member. For instance, to retrieve the age of john, one could write 


(second (member 'mary *age*)) 
SS 


The member function returns the tail of the list beginning with mary, that is, (mary 23 tim 72), and 
second returns the second element of that list, that is 23. While this is one way to access values 
in a property list, the purpose of a convention like property lists is to abstract away from the 
underlying representation (a list) and to provide higher-level functions for working with the data 
structure. 


For property lists, the retrieval function is getf, which takes the property list, a key (more 
commonly called an indicaton, and an optional default value to return in case the property list does 
not contain a value for the key. 


(getf *ages* 'tim) 
¿=> 72 


(gerz *ages* "bob =L) 
¿=> -1 


For updating values in a property list, setf may be used. For instance, when john's birthday 
arrives and his age increases, either of the following could be performed: 


(setf (getf *ages* 'john) 35) 





(incf (getf *ages* 'john)) 
incf works in this case because it is based on setf. 
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To look up multiple properties in a property list as once, use get-properties. 


The getf function searches through the list from left to right, which means that is is possible to 
"mask" values in a property list without removing them from a list or updating any of the structure 
of the list. For instance, using list*: 


(defvar *ages* '(john 34 mary 23 tim 72)) 
(defvar *new-ages* (list* 'mary 29 *ages*)) 


*new-ages* 
¿=> (mary 29 john 34 mary 23 tim 72) 


And now, a lookup for mary will return the first entry: 


(getf *new-ages* 'mary) 
O 


Read Types of Lists online: https://riptutorial.com/common-lisp/topic/3744/types-of-lists 
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Chapter 29: Unit testing 


Examples 


Using FiveAM 





Loading the library 


(ql:quickload "fiveam") 


Define a test case 


(fiveam:test sum-1 
(Comes (= 3 EI 


7; We'll also add a failing test case 
(fiveam:test sum2 
(fiveam:is (= 4 (+ 1 2)))) 


Run tests 


(fiveam: run!) 


which reports 


Running test suite NIL 
Running test SUM2 f 
Running test SUMI . 
Did 2 checks. 

Pass: 1 (50%) 
Skos O Oca) 
Tadia L (50%) 
Failure Details: 





SUME 
CE) 
evaluated to 
3 

which is not 
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ES 





Notes 


e Tests are grouped by test-suites 
+ By defaults tests are added to the global test-suite 


Introduction 


There are a few libraries for unit testing in Common Lisp 


+ FiveAM 

e Prove, with a few unique features like extensive test reporters, colored output, report of test 

duration and asdf integration. 

Lisp-Unit2, similar to JUnit 

e Fiasco, focusing on providing a good testing experience from the REPL. Successor to 
hu.dwim.stefil 


Read Unit testing online: https://riptutorial.com/common-lisp/topic/2349/unit-testing 
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Chapter 30: Working with databases 


Examples 


Simple use of PostgreSQL with Postmodern 


Postmodern is a library to interface the relational database PostgreSQL. It offers several levels of 
access to PostgreSQL, from the execution of SQL queries represented as strings, or as lists, to an 
object-relational mapping. 


The database used in the following examples can be created with these SQL statements: 


create tabl mployees 
(empid integer not null primary key, 





name text not null, 
birthdate date not null, 
skills exe [1 mor mwi ilja 
insert into employees (empid, name, birthdate, skills) values 
(il, “dama Orange“, “1991-07-26; "ME, Javal ir 
(27 “Meny Reds 9504S A Ue, Common tigo, Honechemcost i p 
(3, “Mon Blue", YilS74-Gi=-17", "“(davascriole, Comon Lisah y, 
(4, Vines, cesa", VILIGS—-O2-02", Mueve, veneered} 0), 


The first example shows the result of a simple query returning a relation: 





CL-USER> (ql:quickload "postmodern") ; load the system postmodern (nickname: pomo) 


("postmodern") 
CL-USER> (let ((parameters '("database" "dbuser" "dbpass" "localhost") ) ) 











(pomo:with-connection parameters 
(pomo:query "select name, skills from employees") ) ) 





CONCE Ora nge la (uel Vue) ; output manually edited! 
("Mary Red" #("C" "Common Lisp" "Hunchentoot") ) 
("Ron Blue" #("JavaScript" "Common Lisp") ) 
("Lucy Green" #("Java" "JavaScript") ) ) 
4 ; the second value is the size of the result 





Note that the result can be returned as list of alists or plists adding the optional parameters :alists 
Or :plists to the query function. 


An alternative to query iS doquery, to iterate over the results of a query. Its parameters are query 
(&rest names) &body body, where names are bound to the values in the row at each iteration: 


CL-USER> (let ((parameters '("database" "dbuser" "dbpass" "localhost") ) ) 





(pomo:with-connection parameters 
(format t "The employees that knows Java are:~%") 
(pomo:doquery "select empid, name from employees where skills (> '{Java}'" (i n) 
(format t "ra (id = ~a)~%" n i)))) 
The employees that knows Java are: 








John Orange (id = 1) 





Lucy Green (id = 4) 
NIL 
2 
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When the query requires parameters, one can use prepared statements: 











CL-USER> (let ((parameters '("database" "dbuser" "dbpass" "localhost"))) 
(pomo :with-connection parameters 
(fune ia 
(pomo :prepare "select name, skills from employees where skills @> $1") 
# ("Common Lisp")))) ; find employees with skills including Common Lisp 
(("Mary Red" #("C" "Common Lisp" "Hunchentoot")) 
(Mesa Eiki ey Clulianas Crile common basah) 


2 


The function prepare receives a query with placeholders $1, $2, etc. and returns a new function that 
requires one parameter for each placeholder and executes the query when called with the right 
number of arguments. 


In case of updates, the function exec returns the number of tuples modified (the two DDL 
statements are enclosed in a transaction): 





CL-USER> (let ((parameters '("database" "dbuser" "dbpass" "localhost"))) 
(pomo:with-connection parameters 
(pomo :ensure-transaction 
(values 





(pomo:execute "alter tabl mployees add column salary integer") 
(pomo :execute "updat mployees set salary = 





Case when skills @> '(Common Lisp}' 
then 100000 else 50000 end"))))) 


In addition to writing SQL queries as strings, one can use of lists of keywords, symbols and 
constants, with a syntax reminiscent of lisp (S-SQL): 








CL-USER> (let ((parameters '("database" "dbuser" "dbpass" "localhost") ) ) 
(pomo:with-connection parameters 
(pomo:query (:select 'name :from ‘employees :where (:> 'salary 60000))))) 
(("Mary Red") ("Ron Blue") ) 
2 


Read Working with databases online: https://riptutorial.com/common-lisp/topic/4558/working-with- 
databases 
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Chapter 31: Working with SLIME 


Examples 


Installation 


It is best to use latest SLIME from Emacs MELPA repository: the packages may be a bit unstable, 
but you get the latest features. 


Portale and multiplatform Emacs, Slime, Quicklisp, SBCL and Git 

You can download a portable and multiplatform version of Emacs25 already configured with Slime, 
SBCL, Quicklisp and Git: Portacle. It's a quick and easy way to get going. If you want to learn how 
to install everything yourself, read on. 

Manual install 


In GNU Emacs (>= 24.5) initialization file (~/.emacs Of ~/.emacs.d/init.e1) add the following: 


;; Use Emacs package system 
(require 'package) 








7; Add MELPA repository 
(add-to-list 'package-archives 
'("melpa" . "http://melpa.milkbox.net/packages/") t) 
7; Reload package list 
(package-initialize) 





(unless package-archive-contents 





(package-refresh-contents)) 
Sp List ar packages lo iimsitadlils 
(setq package-list 























' (magit ; git interface (OPTIONAL) 
auto-complete ; auto complete (RECOMMENDED) 
auto-complete-pcmp ; programmable completion 
idle-highlight-mode ; highlight words in programming buffer (OPTIONAL) 
rainbow-delimiters ; highlight parenthesis (OPTIONAL) 
ac-slime ; auto-complete for SLIME 
slime 6 Sibelius, ASC 
eval-sexp-fu ; Highlight evaluated form (OPTIONAL) 
smartparens ; Help with many parentheses (OPTIONAL) 


)) 


Ap Install aie are mor asis lev! 
(dolist (package package-list) 
(unless (package-installed-p package) 
(package-install package) ) ) 


;; Parenthesis - OPTIONAL but recommended 
show-paren-mode t) 
require 'smartparens-config) 


sp-use-paredit-bindings) 


( 

( 

( 

(sa-oaiic VY (Y YY) sumesya Witt (7) 

(define-key smartparens-mode-map (kbd "C-<right>") 'sp-forward-slurp-sexp) 
( 


define-key smartparens-mode-map (kbd "C-<left>") 'sp-backward-slurp-sexp) 
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(define-key smartparens-mode-map (kbd "C-S-<right>") 'sp-forward-barf-sexp) 














(define-key smartparens-mode-map (kbd "C-S-<left>") 'sp-backward-barf-sexp) 
(define-key smartparens-mode-map (kbd "C-)") 'sp-forward-slurp-sexp) 
(define-key smartparens-mode-map (kbd "C-(") 'sp-backward-slurp-sexp) 
(define-key smartparens-mode-map (kbd "C-}") 'sp-forward-barf-sexp) 
(define-key smartparens-mode-map (kbd "C-{") 'sp-backward-barf-sexp) 


(sp-pair uqu wyw :wrap "M-(") 
(sp-pair gu wj :wrap "M-[") 
(sp-pair UN :wrap "M-{") 


;; MAIN Slime setup 

;; Choose lisp implementation: 

7; The first option uses roswell with default sbcl 
7; the second option - uses ccl directly 





(setq slime-lisp-implementations 
((rosuell (Yieos"! VAV Vsloeil—oatin Den) 
eleccion 
VA ari 80) )) )) )) 
AA Otiici SEttilmegs» 4. 


SLIME on its own is OK, but it works better with Quicklisp package manager. To install Quicklisp, 
follow the instruction on the website (if you use roswell, follow roswell instructions). Once installed, 
in your lisp invoke: 

(ql:quickload :quicklisp-slime-helper) 


and add the following lines to Emacs init file: 


7; Find where quicklisp is installed to 





7; Add your own location if quicklisp is installed somewher ES 
(defvar quicklisp-directories 
"("=/.roswell/lisp/quicklisp/" 7; default roswell location for quicklisp 
Ue cuate so Y) pp cerfemule cuilelelisj location 


UPOS Stole locarions oE QUI CRIS e) 


7; Load slime-helper 
(let ((continue-p t) 
(dirs quicklisp-directories)) 
(while continue-p 
(cond ((null dirs) (message "Cannot find slime-helper.el")) 


( 








file-directory-p (expand-file-name (car dirs) )) 





message "Loading slime-helper.el from %s" (car dirs) ) 
load (expand-file-name "slime-helper.el" (car dirs) )) 


( 
( 
( 
(setq continue-p nil) ) 
E 


(e (sete ellos (ecke ciza) dI) 


77 Autocomplete in SLIME 








(require 'slime-autoloads) 
(slime-setup '(slime-fancy) ) 
pi (cequilire ‘ac slime) 





(add-hook 'slime-mode-hook 'set-up-slime-ac) 
(add-hook 'slime-repl-mode-hook 'set-up-slime-ac) 
(eval-after-load "auto-complete" 





'(add-to-list 'ac-modes 'slime-repl-mode)) 
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(eval-after-load "auto-complete" 
"(add-to-list 'ac-modes 'slime-repl-mode)) 


OS 
(add-hook 'lisp-mode-hook (lambda () 
(rainbow-delimiters-mode t) 








(smartparens-strict-mode t) 
(idle-highlight-mode t) 
(auto-complete-mode))) 





(add-hook 'slime-mode-hook (lambda () 
(set-up-slime-ac) 





(auto-complete-mode))) 


(add-hook 'slime-repl-mode-hook (lambda () 
(rainbow-delimiters-mode t) 








(smartparens-strict-mode t) 
(set-up-slime-ac) 
( 





auto-complete-mode))) 
After the restart, GNU Emacs will install and set up all the necessary packages. 
Starting and finishing SLIME, special (comma) REPL commands 
In Emacs m-x slime Will start slime with the default (first) Common Lisp implementation. If there are 
multiple implementations provided (via variable s1ime-1isp-implementations), Other implementations 


can be accessed via m-- m-x slime, which will offer the choice of available implementations in mini- 
buffer. 





M-x slime Will open REPL buffer which will look as follows: 


A Sbs ZOwG—O4— iY) 
CL-USER> 








SLIME REPL buffer accepts a few special commands. All of them start with ,. Once , is typed, the 
list of options will be shown in mini-buffer. They include: 


e- quit 





e „restart-inferior-lisp 
* „pwa - prints current directory from where Lisp is running 
e „ca - will change current directory 


Using REPL 


FUSER (TE) 





-USER> (sin 1.5) 

.997495 

USER (Mapeo ano ES (Gr ox Z)))) ES) 
3 4 5) 














= OY Oi Un ©) 


The result that is printed after evaluation is not only a string: there is full-on Lisp object behind it 
which can be inspected by right-clicking on it and choosing Inspect. 
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Multi-line input is also possible: use c-j to put new line. enter-key will cause the entered form to be 
evaluated and if the form is not finished, will likely cause an error: 





CL-USER> (mapcar (lambda (x y) 
(declare (ignore y)) 
( x 2)) 
"(al 2 3B) 





(2 2 la) 


Error handling 


If evaluation causes an error: 


CTSUSER> (AS 0)) 





This will pop up a debugger buffer with the following content (in SBCL lisp): 


arithmetic error DIVISION-BY-ZERO signalled 
Operation was /, operands (3 0). 
[Condition of type DIVISION-BY-ZERO] 





Restarts: 
0: [RETRY] Retry SLIME REPL evaluation request. 
1: [*ABORT] Return to SLIME's top level. 




























































































2: [ABORT] abort thread (#<THREAD "repl-thread" RUNNING {1004FA8033}>) 
Backtrace: 
0: (SB-KERNEL: :INTEGER-/-INTEGER 3 0) 
is (7 3 ©) 
2: (SB-INT:SIMPLE-EVAL-IN-LEXENV (/ 3 0) #<NULL-LEXENV>) 
SENA SAO) 
4: (SWANK: :EVAL-REGION "(/ 3 0) ..) 
5: ((LAMBDA NIL :IN SWANK-REPL::REPL-EVAL)) 























=== iOS === 


Moving cursor down passed --- more --- will cause the backtrace to expand further. 





At each line of the backtrace pressing enter will show more information about a particular call (if 
available). 


Pressing enter on the line of restarts will cause a particular restart to be invoked. Alternatively, the 
restart can be chosen by number o, 1 or 2 (press corresponding key anywhere in the buffer). The 
default restart is marked by a star and can be invoked by pressing key « (for "quit"). Pressing q will 
close the debugger and show the following in REPL 








; Evaluation aborted on #<DIVISION-BY-ZERO {10064CCE43}>. 
CL-USER> 











Finally, quite rarely, but Lisp might encounter an error that cannot be handled by Lisp debugger, in 
which case it will drop into low-level debugger or finish abnormally. To see the cause of this kind of 
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error, switch to +inferior-1isp* buffer. 
Setting up a SWANK server over a SSH tunnel. 


. Install a Common Lisp implementation on the server. (E.g. sbc1, clisp, etc...) 

. Install Guickiisp on the server. 

. Load SWANK with (ql:quickload :swank) 

. Start the server with (swank:create-server). The default port iS 4005. 

. [On your local machine] Create a SSH tunnel with ssh -14005:127.0.0.1:4005 [remote 


machine] 


. Connect to the running remote swank server with m-x slime-connect. The host should be 
127.0.0.1 and the port 4005. 


akwND — 


o 





Read Working with SLIME online: https://riptutorial.com/common-lisp/topic/4097/working-with- 
slime 
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